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

Annotations only declare destructiveHint=false and readOnlyHint=false; the description adds the far more important behaviors: a person decides on the Business map so no system changes, evidence-first evaluation that returns contradicted with evidence instead of opening a review, the exists/on_map outcomes, and a report-validation policy that refuses the whole report on fractions, negatives, impossible counts, or notes over 300 characters. This is context an agent could not obtain from annotations or schema.

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?

Almost every clause carries information, and the purpose and the confirm-flow are reasonably front-loaded. But it is delivered as one dense, run-on block mixing flag behavior, report behavior, privacy rules and outcome names, making it hard for an agent to parse on a single pass — structure, not length, is the problem.

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?

For a 10-parameter tool with nested objects and no output schema, the description covers the outcome vocabulary (contradicted, opened with review_id, exists, on_map), the report-then-read sequence, and the hard privacy rule against sending values, rows, names or ids from the data. Minor gap: the exact shape of the opened/signal payload is only gestured at via 'review_id from the signal's task context'.

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 semantics the schema does not: cardinality must be read from → to, key must be passed exactly as route/get_object returned it, note max length differs between 300 (measurement) and 500 (flag), and counts must be internally consistent or the report is rejected. It also explains per-reason field requirements beyond the enum descriptions.

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 opening states concrete verbs and objects — question a join, add a missed join, or report counts on a review — so the agent can tell this is a join-review mutation tool, not a read tool like get_object or route. It is specific but the sentence is grammatically tangled ('a join_review signal whose task context says what to count'), and it never explicitly names a sibling it is not.

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?

It gives explicit branches: use flag to open a review (with reason-specific requirements: cardinality for wrong_direction, note for works_like_this, key or note for missed), use report to record counts on an existing review. It also states the when-not path — if Maplith's evidence contradicts the claim, nothing opens and you must only retry with confirm:true after the human has seen the evidence — and points to route/get_object as the source of the key.

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