generate_report

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

With no annotations provided, the description carries the full behavioral burden. It explains that the PDF is the primary deliverable, that the return value additionally includes the same metrics as a structured quality block, and that availability depends on training via the MCP train tool. This is meaningful behavioral context, though it does not specify what happens when the report is unavailable or how output_path behaves when omitted.

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-organized and front-loaded: the deliverable is stated first, then the page breakdown, then the return-value behavior, then the constraint about older models. Each sentence adds necessary information and there is no filler or repetition of schema details.

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?

The description covers the report's content, the structured return value, and the dependency on holdout data from the train tool, which is the core non-obvious context. It is missing a few operational details such as output_path default behavior and how the tool signals unavailability, but it is largely sufficient for an agent to decide whether and how to invoke this tool.

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 description coverage is 0%, so the description must compensate for the input schema. It does not explain model_id requirements or the behavior of output_path (e.g., what happens when null or how the default path is chosen). The usage context implies model_id refers to a trained model, but explicit parameter-level guidance is missing.

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 names a specific deliverable ('procurement-style model-quality PDF report') and details the exact page-level contents, so an agent knows precisely what this tool produces. It also differentiates the tool from siblings by noting the returned quality block is 'identical to get_model_quality', which clarifies the relationship to that nearby tool.

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: use this when you need a human-readable PDF report, and it notes that the structured metrics are available for reasoning. It also warns that the report may be unavailable for older models and explains why (reliance on holdout data from the MCP train tool). It does not explicitly say 'use get_model_quality instead when you only need metrics', so it stops short of a complete routing guide.

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