Archive a GitHub project item

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations it discloses the concrete effect (the item leaves the board's views and github_project_read's item_list unless include_archived), that nothing is deleted, the idempotent no-op result (changed: false), and the auth prerequisite including the recovery step (gh auth refresh -s project). The annotation destructiveHint=true sits alongside "Nothing is deleted", but the description is clarifying scope (removal from views, reversible) rather than denying a state change, so this is a useful clarification rather than a contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The critical facts (what it does, that it is reversible, that it is a no-op if already archived) are front-loaded, which is good, but the description then becomes one very long run-on explaining the entire project-lookup resolution chain. Much of that detail duplicates the 100%-covered schema descriptions, so several clauses do not earn their place in the tool description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with an output schema and full annotation coverage, the description supplies everything an agent still needs: precondition (update permission), side effects, reversibility, idempotent behavior, identifier formats, project resolution rules, and the token-scope failure mode with remediation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real resolution logic the schema only hints at: a project given beside a node ID must match that item's board, and a title is looked up in owner's boards, else boards linked to repo, then its organization, then the viewer's, and is "never guessed". That extra ordering and constraint meaningfully reduces wrong-argument calls.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Archive an item on a project board") plus the precondition ("a board the viewer may update"), and it names the inverse sibling github_project_item_unarchive explicitly, so an agent can separate it from the unarchive and item_edit tools without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance and alternatives: use github_project_item_unarchive to bring the item back, and note that already-archived items are a no-op rather than an error. It also spells out the accepted identifier forms for item and project (PVTI node ID, 12 / #12 / owner/repo#12 / URL, board number / owner/number / URL / title), which is the main ambiguity an agent would hit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.