List fork README diagrams

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

No annotations are provided, so the description carries the burden. It's clearly a read-only listing operation ('list... with reference originals and descriptions'), which is implicitly non-destructive. However, it doesn't disclose return format, pagination, or ordering behavior. For a simple list tool with no annotations, this is adequate but not rich.

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?

Single sentence, zero waste. Every element earns its place: the verb, the resource, the ID range, and the output content. This is an example of efficient minimal specification.

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 parameterless list tool, the description is quite complete. It conveys what will be listed (ids, reference originals, descriptions) and the scope (svg-07..svg-12). There's no output schema to supplement, so the description itself carries the return-value expectation, which it does reasonably well. Could optionally name sibling tools like generate_all_fork_diagrams as next steps, but that's a minor gap.

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 tool has 0 parameters, so there are no parameter semantics to explain. The baseline of 4 for 0-parameter tools applies. The description's mention of 'reference originals and descriptions' hints at the expected output content, which adds useful context beyond the empty schema.

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 states the tool 'List diagram ids' with a specific resource (fork README diagrams) and the specific IDs range (svg-07..svg-12). It distinguishes from sibling tools like generate_diagram and preview_diagram by clarifying this is a listing function, not a generation or preview tool. Clear verb+resource+scope.

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 this is a discovery/preview tool ('list diagram ids the generator can produce'), which suggests using it before generating. However, it doesn't explicitly name alternatives or state when-not-to-use. Sibling tools like generate_all_fork_diagrams imply this is a precursor, but the description doesn't make that relationship explicit.

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