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

Annotations already declare a non-read-only, non-destructive, non-idempotent, closed-world write. The description adds genuinely new behavioral context on top: each report is checked against the official record or the lawyer's own website and corrected in the next update, and a report never affects the order or placement of any lawyer. It also sets a hard content constraint (no case details, no contact details of the reporter) and the no-payment-for-placement policy. It does not say whether duplicate reports are deduplicated or whether the reporter receives confirmation, which matters given idempotentHint=false.

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 trigger condition and required inputs are front-loaded in the first two sentences, and the remaining sentences are short and purposeful. There is minor redundancy between "A report never changes the order or placement of any lawyer" and the closing "No lawyer pays for placement or ranking of any kind," but each still carries a distinct policy point.

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 6-parameter write tool with an output schema, the description covers the trigger, the required inputs, the post-submission process, the non-effect on ranking, and the content restrictions. Return values need not be explained because an output schema exists. The only real gap is sibling routing, which is a usage-guideline concern rather than a completeness one.

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 83%, so the schema already explains attorney_id, field, note, reporter and correct_value. The description's parameter sentence ("Pass the listing's attorney_id, which detail, and optionally the correct value") restates the schema without adding format, sourcing, or enum guidance. The privacy constraint on note/correct_value is useful but already appears in the schema descriptions, so this dimension sits at the baseline.

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 names a specific action and resource: reporting that a detail on a lawyer listing is wrong, missing or out of date, and it enumerates the fields that qualify (phone, website, office, firm, practice areas, license status, languages, fees, availability, name). An agent can tell this is an error-reporting tool rather than a search or introduction tool. It does not, however, distinguish itself from the sibling submit_listing_feedback, which reads as an adjacent capability.

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?

"Use when the person (or the listed lawyer) says a detail on a listing is wrong, missing or out of date" gives a clear trigger condition and even covers the self-reporting case. It also states what to pass (attorney_id, which detail, optionally the correct value). What is missing is any exclusion or routing versus submit_listing_feedback and the other feedback tools, so the agent must guess which one to call.

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