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

Annotations already state idempotentHint=false and readOnlyHint=false, but the description adds valuable context: it records a new proposal each call (non-idempotent) and explicitly assures that it does NOT modify the repository or open a PR. It also reveals that the tool resolves a target path and returns content for the user to write, which is a non-obvious behavioral trait. This goes beyond the annotations, though it doesn't mention permissions or rate limits.

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 description is well-structured and front-loaded with the primary purpose. Each sentence contributes meaning: purpose, non-idempotency, non-modification behavior, the resolution process, the return value, and the parameter constraint. While it is longer than the two-sentence high example, it packs substantial necessary detail without fluff, and the repetition of the return value is minor but not wasteful.

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?

Given the tool's complexity (7 parameters, side effects, resolution logic), the description covers the core workflow well: it tells the user what to do (propose), what to expect (resolved path and content), and a key constraint (targetPath or baseSlug). It does not explain edge cases like the repository parameter behavior (covered in the schema) or what happens if both targetPath and baseSlug are provided, but that is not critical. The return value is minimally described, which is sufficient given no output schema.

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?

The input schema already provides descriptions for all 7 parameters (coverage 100%), so the baseline is 3. The description adds the mutual exclusivity rule 'Provide either targetPath or baseSlug', which is not in the schema, and clarifies the return value (resolved path and content). This enriches the parameter semantics without repeating the schema's field descriptions.

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?

The description clearly states the tool's purpose: to propose a documentation file to add or update. It specifies the verb 'propose' and the resource 'documentation file', and distinguishes itself from sibling tools by focusing on add/update rather than removal or read-only queries. It also clarifies that it returns a path and content for the user to write, making its role unambiguous.

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?

The description gives clear context for when to use this tool: as part of the current change, when adding or updating docs, and it explains the workflow (returns path and Markdown for the user to write). It does not explicitly name alternatives (like propose_doc_removal) or state when not to use it, but the sibling context and the 'Propose...' phrasing imply the appropriate use case. It also provides a key constraint: provide either targetPath or baseSlug.

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