Get Inventory Judgements

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

With no annotations, the description carries the burden and largely meets it: 'Read-only: no model is called and nothing is queued' discloses the absence of side effects and computational cost, and the status vocabulary (complete/partial/not_evaluated with reason, legacy) explains what missing coverage means. It does not discuss payload size, permissions, or whether results are cached/stale beyond the legacy case.

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?

Front-loaded correctly — purpose and read-only guarantee come first. But the middle is a dense, punctuation-heavy enumeration of every returned field and status value, which partly duplicates the declared output schema and crowds out operational guidance. It is information-dense rather than concise; several clauses (e.g. the full definition of one_sided/disputed) could be trimmed given the schema exists.

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?

An output schema exists, so the long return-value walkthrough is largely redundant, while the genuinely missing pieces — the meaning of server_version, and an explicit rule for choosing this tool over get_review_queue — remain unaddressed. The semantic gloss on statuses is valuable, but the description allocates its length poorly relative to what an agent actually needs to call it.

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 only 50%: model_id is documented in the schema, while server_version is undocumented in both schema and description, so an agent has no idea what value to supply for a required parameter. The description only alludes to 'a model's inventory' and adds nothing about either parameter's format or source. For a 2-required-param tool with a required opaque parameter, this leaves a real invocation gap.

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 the results of per-entity checks about a model's inventory, and explicitly notes what it is not ('no model is called and nothing is queued'). The term 'inventory judgements' is domain jargon that an outsider cannot decode from the name alone, but the body defines it. Sibling differentiation is implicit rather than explicit — decide_inventory_pair and request_inventory_checks are named as the action counterparts.

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?

Gives clear routing context: disputed pairs go to a person, decide_inventory_pair records the decision, request_inventory_checks requests the checks owed, and the same rows surface via get_review_queue. That is a usable map of alternatives. It stops short of stating when NOT to use this tool (e.g. versus reading a batch through get_review_queue).

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