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

Annotations only declare destructive/not-idempotent/open-world; the description supplies the concrete stakes and mechanics: a $1 fee, two mutually exclusive payment rails, a mandatory preflight with exact before/after balance, refusal rules that fire before any fee, the constraint that only one trait may carry a wake key, and that variants "never select randomly." That is substantial behavior disclosed beyond structured fields.

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 purpose is front-loaded and nearly every clause carries a constraint, but it arrives as one dense run-on paragraph with no separation between payload rules, payment rules, and refusal rules, which slows scanning for a 9-parameter tool. The recipe bounds (64 rows, 1,024 total ingredients, 65,536 UTF-8 bytes) duplicate the schema's own description word for word, and the phrasing "the exact $1 city fee" is oddly compressed.

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 complex write tool with no output schema and 9 parameters, the description covers payload validation, payment preflight, and refusal conditions thoroughly. It leaves unstated what a successful call returns (new kind identifier?), what happens to the spent credit or a duplicate `name` on failure, and why the operation is flagged destructive — gaps that matter for a credit-spending mutation.

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 coverage at 44%, the description carries real weight: `traits` is "the kind's whole trait list" replaced wholesale by revise_kind and must reference *existing* traits; `drawing` must match the exact null/REFUSE/pixel shapes of `draw_self` with explicit `drawing_state`; `city_credit_request_id` must be the preflight-returned id rather than an invented number. The recipe limits and description length, however, are restated verbatim from the schema rather than adding meaning.

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?

"Invent a public kind for the exact $1 city fee" names a specific verb, the resource created, and its cost, and the description later contrasts itself with `revise_kind` ("a later revise_kind replaces it whole"), so an agent can separate creation from revision without opening a schema.

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 routes the agent well: call `credit_preflight` and show the balance before a credit-funded invention, then use a fresh `city_credit_request_id` or the X-PAYMENT header but never both, and it states a when-not (trait using `law_place` or `convert` with `into_kind` is refused because "those steps are for laws"), plus a fallback to `front_door`. It stops short of explicitly saying to use `revise_kind` for edits to an already-existing kind, which is only implied.

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