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

The description explicitly discloses side effects beyond the annotations: 'consumes AI credits, creates a generation, and optionally writes markdown to a Space after authorization.' This is highly informative and goes beyond the readOnlyHint=false annotation, which only implies state-changing. It also mentions the need for authorization, setting accurate expectations for the agent.

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 concise at three sentences, with the primary use case front-loaded in the first sentence. The second sentence covers side effects, and the third gives additional guidance. No unnecessary words or repetition; it is well-structured for quick parsing.

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 state-changing tool with a nested optional object and no output schema, the description covers the main behavioral aspects (credit consumption, generation creation, optional Space write) and the schema fully documents parameters. It does not explicitly mention what the tool returns (e.g., a generation ID), but this is not unusual and might be handled by follow-up tools. Slight omission but not a major gap, so a 4 is appropriate.

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 schema provides descriptions for all parameters (100% coverage), so the baseline is 3. The tool description adds no additional clarification or examples about parameters themselves, such as how to specify diagram_type or the relationship between filename and source_code. It does not exceed the schema-provided information, so it stays at the baseline score.

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: generate UML/Mermaid/sequence/class/component/architecture diagrams from user-supplied source code. It includes a specific verb 'generate' and resource 'UML diagram', and the usage context distinguishes it from other generation tools by referencing source code and specific diagram types.

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 explicitly tells when to use the tool: 'Use this when the user supplies source code and asks for UML, Mermaid, sequence, class, component, or architecture diagrams.' It also provides additional guidance for a specific scenario ('Use browser guidance for local uploads or full repository diagrams'), and notes that it is state-changing and requires authorization for optional Space writes. This gives clear direction on when and how to invoke it without needing to infer from alternatives.

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