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

Beyond the readOnlyHint annotation, the description discloses that the tool requires an open session, that errors are returned inline per slot, and that it leverages a single session dataset build to reduce round trips. These are important behavioral details not present in the annotations.

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 and well-structured, starting with the core capability, then parameter details, then usage guidance. It avoids unnecessary filler and communicates everything needed in a compact format.

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 all necessary context: the batching capability, the parameter structure, the response behavior (what each results slot contains), the session prerequisite, and alternatives for single or one-off evaluations. Despite lacking an output schema, the description sufficiently explains the expected result format, making the tool fully usable.

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 description elaborates on the 'requests' parameter, specifying the structure of each item: '{view|source|templateid, periodStart?, periodEnd, ...}'. This adds crucial semantic information that the schema alone (which only says 'items: type object') does not provide, making the parameter fully understandable.

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 that the tool evaluates up to 24 report templates/views in a single round trip, using specific terms like 'evaluate', 'templates/views', and 'session dataset build'. It also distinguishes itself from sibling tools by mentioning the batch nature and session requirement.

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?

Explicitly provides when to use this tool versus alternatives: 'for a single view use evaluate_report_session, or evaluate_report for a one-off outside any session.' It also states the prerequisite 'Requires an open session (open_report_session first)', giving clear guidance on usage conditions.

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