namespace ClaudeDo.Worker.External;

/// <summary>
/// Boilerplate clauses shared by several external MCP tool descriptions. Every tool description is
/// still emitted in full to the client — these constants only stop the wording from drifting apart
/// across ~50 attributes.
///
/// Description style (keep new tools in line with it):
///  1. First sentence says what the tool does AND when to reach for it — MCP clients rank tools by
///     this text, so the trigger must not be buried behind return-shape prose.
///  2. Then only non-obvious preconditions and refusals.
///  3. Document parameters with [Description] on the parameter, not in the tool description.
///  4. Describe result fields only where the caller must branch on them (isEmpty, truncated,
///     conflicts, …). Everything else is visible in the first actual response.
///  5. No design rationale or "since this feature was introduced" history.
///  Budget: ~400 chars for a simple tool, ~800 for the merge/review family.
/// </summary>
internal static class McpToolDocs
{
    /// <summary>Warns that the payload is the lean reference, not the task's description/result.</summary>
    public const string LeanTaskRef = " Returns a lean task reference, not the task's description.";

    /// <summary>Batch-size cap shared by every BatchMcpTools entry point.</summary>
    public const string MaxBatch = " Max 100 per call.";

    /// <summary>Mutations that refuse to touch a task while its agent is running.</summary>
    public const string NotWhileRunning = " Refused while the task is Running — cancel it first.";

    /// <summary>
    /// Explains this project's diff3 conflict-marker layout so a caller grepping only for
    /// "&lt;&lt;&lt;&lt;&lt;&lt;&lt;/=======/&gt;&gt;&gt;&gt;&gt;&gt;&gt;" doesn't mistake the "|||||||" base section for one of the two sides.
    /// No leading space (unlike the other consts here) since it also doubles as a DTO field default value.
    /// </summary>
    public const string Diff3Note =
        "Conflicts are parsed in git's diff3 style: each hunk has an 'ours' side (the target branch) and a " +
        "'theirs' side (the branch being merged in), plus an optional 'base' — the common-ancestor text for that " +
        "hunk, shown between a third '|||||||' marker and the '=======' separator. base is null when git recorded " +
        "none for that hunk.";
}