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

Annotations already declare it a non-read-only, idempotent, non-destructive write, but the description adds real behavior the annotations cannot express: trusted tokens apply immediately while others are queued for moderation, and every edit is audited with before/after values. The one gap is edit semantics — it never says whether omitted fields are left untouched or cleared, which matters for a partial-update mutation.

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?

Dense and front-loaded: the agent-token gate comes first, then the fact list, then moderation behavior, then the provenance rule. Some space is spent repeating enum values that the schema already enforces, which is the only real waste in an otherwise tight description.

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 an 11-parameter mutation with no output schema and thin schema documentation, the description covers access gating, moderation timing, auditing, and provenance well. It is still incomplete on two things an agent must get right: whether the update is partial or full-replacement, and what `reason` is for, despite that field being central to the audited edit workflow.

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?

With schema description coverage at 27% across 11 parameters, the description carries real burden and does partially compensate by restating the enum vocabularies (wifi yes|spotty|no, noise quiet|mixed|loud) and giving an hours format example. However, it omits `reason` entirely and says nothing about `slug` or `source_url` semantics beyond what the schema already documents, leaving the most audit-relevant field unexplained.

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: "Correct first-hand facts for one spot," followed by the exact fact categories it governs (hours, wifi, outlets, noise, calls, best_time, notes, access_tips). An agent can distinguish this from sibling tools like add_media_link or suggest_spot without opening the schema. It stops short of naming which sibling to use when a spot does not yet exist.

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?

"Partner agents only (agent token required)" gives a clear access precondition, and "Never copy facts from Yelp or Google" plus "first-hand facts" define what input is acceptable. Missing is explicit routing versus suggest_spot (new venue) or get_spot (read), so the agent must infer that this is for correcting an already-listed spot.

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