study_references

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

Annotations flag destructiveHint=true and readOnly=false, which would otherwise be alarming for a measurement tool; the description resolves this by stating it writes nothing unless save_as is given, and the save_as documentation explains that it replaces an existing set of the same name. The interpretive caveat 'Measurements describe habits, not quality' is genuinely useful context an agent would not get from structured fields. No contradiction, though overwrite scope/loss is only implied rather than spelled out.

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?

It is dense but every clause carries information: what is measured, how kind is resolved, the write condition, and the output shape. The single most important safety fact (writes nothing unless save_as) sits late rather than front-loaded, which is the main structural weakness.

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?

With an output schema present, the description need not detail return values, yet it still summarizes them ('per-vehicle metrics and the min-max range per kind'). Combined with the measurement scope, kind resolution, and write semantics, an agent has enough to call it correctly; only the sibling routing is left implicit.

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 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains that kind is auto-detected from road wheels and marine propulsion, and gives a decision rule for when to override it with 'other'. That is parameter guidance the schema only states as an enum, not as behavior.

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?

A specific verb and resource ('Measure how vehicles the player rates are built') followed by an enumeration of exactly what is measured (slope piece sizes, pyramid/inverse pairing, ballast, sub-bodies, detail parts, paint, logic) makes the intent unambiguous. It does not name the nearest siblings (analyze_vehicle, score_vehicle) to differentiate itself explicitly, which keeps it off a 5.

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?

Usage guidance is present but mostly about one parameter: 'kind is detected ... unless given' and 'mark hovercraft, aircraft and unusual builds "other" so they don't widen the boat range.' The write-vs-read condition is also stated ('Writes nothing unless save_as is given'). However, there is no direct statement of when to pick this over analyze_vehicle or score_vehicle, so an agent must infer the routing.

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