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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value beyond that: pagination via offset ('Continue nextOffset'), the gating context ('works while managed binary production is gated'), what it does not check (local working copies not final-approved), and a usability warning. It enriches the behavioral profile without contradicting any annotation.

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?

Every sentence earns its place and the main purpose is front-loaded. 'Continue nextOffset' is terse but adds pagination information. Some domain jargon ('managed binary production is gated', 'real buyer original') lacks expansion, which reduces accessibility for a non-Helvabase agent.

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 tool has 5 parameters (with a nested expectedRevision object) and no output schema, yet the description offers no meaning for the required expectedRevision or documentId fields. It partially describes the return content, safety profile, and use of the sibling, but a caller cannot reliably invoke it correctly without additional knowledge of those parameters. Adequate but not complete.

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 only 20%; only projectId has schema-level meaning, and the description does not compensate well. It references offset ('Continue nextOffset') but does not explain the required nested expectedRevision (outputJobId/payloadHash) or documentId semantics. A caller still cannot determine what to supply for 4 of 5 parameters from the description or 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?

States a specific verb and resource ('Read a bounded inventory of fields to fill in a real buyer original') and enumerates the carried content (revision, evidence, missing values, approval state). It also names the sibling it is not ('Use read_filling_field for each actual value'), so an agent can distinguish between the inventory view and per-value reads without opening schemas.

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?

Points to the explicit alternative (read_filling_field) and gives a strong exclusion ('Never reconstruct a complete original from source excerpts'). It also notes when it works ('while managed binary production is gated') and caveats about local working copies. It could say more directly when to prefer this tool versus other read siblings, but the routing to read_filling_field covers the central decision.

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