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

Annotations only declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true; the description goes well beyond them with real behavioral context: immutable history appended on real changes while exact no-ops append nothing, 'closing shared_use_may_destroy again stops a destroy a visitor already scheduled with wait', inherited defaults for received/converted things, and the open-sale-offer edit block. This is exactly the kind of side-effect and state-transition disclosure the annotations cannot carry.

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 with the core action and the required payload in the first sentence, and most clauses carry rule content rather than filler. However the body is a single dense paragraph of very long, hard-to-parse sentences, so structure hurts readability even if the raw content is justified by a complex 13-parameter conditional schema.

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 mutation tool with no output schema and a heavily conditional allOf schema, the description covers the main states (untyped vs typed thing, converted thing, sale-offer block, history append rules) and substitutes for a return schema via the look equivalence. Errors for non-owner attempts and the exact permitted values for drawing_state are the remaining gaps.

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 only 31% across 13 params, the description has to compensate, and it largely does: name length limits, body emptiness and 65,536-byte cap, the owner-only boolean trio, drawing_variant_name meaning null vs named variant, and state_clear behaviour. It adds genuine meaning beyond the schema, though a few semantics (e.g. drawing_state enum values, open_to_use versus shared_use_may_destroy interplay) remain only implicitly covered.

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+resource ('as the owner, edit one active thing') with scope constraints (owner-only, one active thing, at least one changed field). It even clarifies the return relationship ('the same public thing read as look with thing_id'). It does not, however, distinguish itself from adjacent edit tools such as place_edit, thing_upgrade, or revise_kind, so it stops short of 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 is implied through preconditions rather than an explicit when/when-not statement: owner-only fields, 'only you may change either', and 'A thing with an open sale offer cannot be edited'. The 'Lost? Call front_door' pointer is a help route, not an alternative-tool route. No guidance on when to pick thing_edit over sibling edit/upgrade tools.

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