list_templates

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

No annotations are provided, so the description carries the full burden. It states it's a listing operation (implies non-destructive read) but doesn't disclose whether templates are recursive or just at root level, what happens if no templates exist, or path conventions used. With no annotations, a read operation is reasonably implied by 'List', which carries moderate weight, but richer behavioral detail would strengthen it.

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?

A single sentence that is efficient and front-loads the core purpose ('List all available PR/MR templates'). The only minor gap is that it doesn't add behavioral notes within the same concise structure, but for the size, it's appropriately lean with zero wasted words.

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?

This is a simple read/list tool with a single parameter and no output schema. The description adequately covers the core purpose. Without an output schema, it could usefully hint at the return shape (e.g., template names/file paths), but for a list tool the purpose and scope are reasonably communicated. Does not describe edge cases (no templates found) or template discovery nuances.

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% with the single cwd parameter already documented as 'Working directory — must be inside a git repository'. The description adds nothing about the parameter, but since coverage is complete and the schema description is adequate, the baseline of 3 applies. I rate slightly higher (4) because the schema's own parameter description is notably self-sufficient and precise, covering the git-repo prerequisite that would otherwise belong in the tool description.

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 uses a specific verb+resource ('List all available Pull Request / Merge Request templates') and clearly states the scope is limited to what's 'found in the repository'. It distinguishes from siblings like prepare_merge_request and publish_merge_request, which are action verbs on the same domain; listing is clearly separate. A slight deduction because it doesn't explicitly contrast with get_repo_info, though the resource type is different enough.

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 implies a read-only overview use case (before preparing or publishing an MR/PR). However, it doesn't explicitly state when to use this vs alternatives, nor does it provide exclusions like 'use this before prepare_merge_request' or mention a preferred alternative for other listing needs. Context is inferred from 'found in the repository' but not made explicit.

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