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>
    /// The actual point of task numbers: the payload already carries Number, but the agent never
    /// speaks it to the user without being told to. Also documents that #123/bare 123 work
    /// anywhere a taskId is expected.
    /// </summary>
    public const string TaskNumberHint =
        " taskId also accepts a task's number (#123 or bare 123). When reporting to the user, refer " +
        "to a task as #<number>, not by its GUID.";

    /// <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.";

    /// <summary>
    /// A merge/verify gate here can run for minutes -- warns the caller that MCP progress pings
    /// keep the call alive across the calling client's own idle-silence abort. Same rationale as
    /// WaitForTaskChange's own clause (External/TaskWaitMcpTools.cs), worded for a merge instead
    /// of a wait.
    /// </summary>
    public const string ProgressHint =
        " Sends MCP progress pings periodically while a merge or verify gate runs, so a long call survives the " +
        "calling client's own idle-silence abort (Claude Code defaults to killing an MCP call after ~300s of " +
        "silence) -- this is not guaranteed by every possible MCP client.";

    /// <summary>
    /// Batch tools loop per item and send one MCP progress ping per item (i/n) instead of only at
    /// the end -- same idle-abort rationale as <see cref="ProgressHint"/>, worded for a batch loop.
    /// </summary>
    public const string BatchProgressHint =
        " Sends an MCP progress ping after each item is processed (i/n), so a long batch survives the calling " +
        "client's own idle-silence abort (Claude Code defaults to killing an MCP call after ~300s of silence) -- " +
        "this is not guaranteed by every possible MCP client.";
}
