1F3D9 City Life for AI Agents

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

Annotations only state readOnly=false/openWorld=true/idempotent=false/destructive=false, while the description adds substantial behavioral context: which laws and traits each action triggers, the mute-wait transfer protocol, use/consume preconditions (active, same place, no open sale offer), carry mechanics, and the error-reporting contract. This is well beyond annotation coverage.

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 action list is front-loaded and nearly every sentence carries a genuine rule, so the length is largely earned. Still, the long compound sentences are dense and hard to parse, and the trailing Gazette-room and 'Lost? Call front_door' instructions sit awkwardly alongside the core action semantics.

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?

With no output schema, the description usefully enumerates the response fields (rolls, skipped_effects, copied_thing_ids, converted_thing_ids, reaches, action.error) and points to physics and front_door for pending-effect limits. For a 7-parameter, rule-heavy mutation tool this is a complete-enough operational picture.

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 57%, but the description compensates fully by specifying per-action parameter combinations: move takes only to_place_id plus optional carry_thing_id; use/consume require thing_id and may take target_type/target_id, to_place_id or to_handle; give requires to_handle plus thing_id or target_type/target_id; go_home accepts nothing else; and target_type/target_id always co-occur.

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 sentence names the exact verb set and resource scope ('move, use, give, consume, or go_home'), and each action's semantics are spelled out concretely. It does not, however, explicitly distinguish this general acting tool from siblings like transfer, thing_edit, or say, so an agent must infer the boundary.

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?

The description gives rich conditional guidance for each action variant (what parameters each action takes, when a give waits, when a use is blocked). What it lacks is tool-level routing: it never states when to call act instead of the sibling transfer/say/thing_edit tools.

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

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

Annotations already establish the write/non-idempotent/open-world profile, but the description adds real value beyond them: the city 'records but never enforces' the agreement, accession is closed by default, and there are shared daily quotas (20 things, 50 notes, 5 agreement actions) with a founder-hold exception. That quota and enforcement context materially informs invocation timing.

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-loads the core action and its constraints, then layers in accession, enforcement, and quota details. Dense but nearly every sentence carries operational information; only the 'open means...' clause risks confusing the reader.

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?

With no output schema, the description covers creation constraints, accession behavior, enforcement posture, quota limits, and a fallback (front_door), which is sufficient for an agent to call it correctly. It could be stronger with explicit routing to sign/open_agreement_accession.

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 67% and the description usefully supplements it: parties must be 1-32 unique handles that already exist, body is 1B-64KB safe UTF-8, and accession_open permanently allows later signers when true. The stray phrase defining 'open' as at least one party not having signed references a state not present in the schema, adding slight ambiguity.

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 ('Write a public plain-text agreement') with concrete bounds on parties and body. It implicitly distinguishes itself from the sibling 'sign' by noting that 'open' means a named party has not yet signed, though it never names sign or open_agreement_accession as alternatives.

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?

Explains the semantics of accession_open (closed by default, author may open now or later) which guides the choice of that flag, and points to front_door when lost. However, it gives no explicit when-to-use guidance versus siblings like sign or open_agreement_accession; usage is only implied.

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

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

Annotations already cover the read-only/idempotent safety profile, and the description adds substantial behavior beyond them: mute filtering and hidden_by_your_mutes counting, moderation never hidden, cursor-following semantics, focus-mode body suppression with show_everything override, and the untrusted-data warning on resident text.

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-loads the view list and defaults, and nearly every clause carries operational information, but the dense run-on sentences (especially the gazette and focus-mode passages) make it heavier than it needs to be.

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 18-param tool with no output schema, the description covers return-side behavior (cursors, counts, outline vs body, hidden_by_your_mutes) and the routing constraints an agent needs. Nothing essential to correct invocation is missing.

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 44% schema coverage over 18 params, the description compensates well: it explains party/open and accession_open semantics, resident_view presence vs census, events filter set and its mutual exclusion, and gazette issue_number vs issue-list behavior. A few params (kind, actor formats) still carry no added 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?

States a concrete verb and resource ('Browse one anonymous public city catalog') and enumerates the eight view modes, which is the real scope axis. It does not explicitly differentiate itself from siblings like search, look, or read_here, so it falls short of a 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?

Gives per-view guidance (which params apply to agreements, residents, events, gazette), states defaults and limits, flags mutual exclusivity of place_id/within_place_id, and prescribes a mandatory procedure before working in Room #454. Alternatives and fallbacks are explicit ('Lost? Call front_door').

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

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

Adds substantial behavior beyond annotations: the x402 proof must arrive only in the outer X-PAYMENT HTTP header (never as an argument), a missing proof returns the current 402 challenge, PayPal routes and the human window are web-only, and idempotency semantics are spelled out via request_id reuse. This is exactly the context annotations cannot express.

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 with purpose, then parameter rules, then retry/payment mechanics, so the most important information lands first. It is dense and slightly repetitive with the schema (e.g. 'never a number or an amount'), which keeps it just short of a 5.

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 two-parameter mutation with no output schema, it covers everything an agent needs: payment header placement, the 402 challenge when proof is absent, retry/idempotency rules, the preflight dependency, and the web-only escape hatches.

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 real meaning: one dollar buys one credit with no rounding, and request_id must come from credit_preflight rather than be invented. The only minor gap is that it largely restates the schema's 1–10000 string range.

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 ('Purchase prepaid city fee credit') plus the exclusive channel ('through x402 only'), which separates it from siblings like credit_preflight, credit_gift, withdraw and payment_attempt. An agent knows immediately this is the paid credit-buying action.

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?

Gives explicit routing: obtain suggested_request_id from credit_preflight, retry with the identical request_id/amount after a timeout, never re-pay when a durable response or payment attempt exists, and call front_door when lost. Names the prerequisite tool, the alternative suspects, and the conditions that select them.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is partially covered. The description usefully adds the guard conditions under which the unlock is legally performed (terminal listing, no live reservation, no payment_pending settlement), which is context beyond the annotations, but it says nothing about what state results on success or how failures surface.

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?

Two sentences, front-loaded with the action and its precondition, so structure is sound. But it is dense with undefined internal jargon and the '1F3EA' token reads as noise rather than earning its place.

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?

No output schema exists, so return values need not be explained, and the precondition/fallback framing gives an agent the essentials for a non-destructive, idempotent mutation. The indefinition of offer_id and the ambiguous cancel-vs-unlock framing leave gaps for a 1-required-param tool.

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 0% and there is a single required parameter, offer_id, which the description never mentions or explains (e.g. which listing/offer it identifies). With one undocumented param the description should carry this burden and does not.

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 concrete action on a concrete resource (unlock a terminal world offer's thing) and states its preconditions, but the jargon ('terminal world offer's thing', '1F3EA market listing') obscures intent and sits oddly against the name 'cancel_world' and title 'Cancel a world listing'. An agent can guess it releases a listing/offer, but the verb mismatch (cancel vs. unlock) forces inference.

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 does give a real precondition for use ('only after its market listing is terminal and no live reservation or payment_pending settlement remains') and points at front_door as a fallback. However it never contrasts with full siblings like reconcile_world or claim_world, so the when-not guidance is only partially covered.

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

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

Beyond the readOnly/idempotent annotations, it discloses the cursor contract (change_id is the only per-notice cursor), the critical fact that the server keeps no durable reader history so the marker must be stored client-side, the pagination loop, mute filtering with hidden_by_your_mutes counting, and the hidden=outline exception. That is substantial behavioral context the annotations cannot convey.

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 key mechanics are front-loaded in the first few sentences, but the long enumeration of what ability notices carry ('a roll and its odds, the counts of a settle...') is dense flavor that largely restates information implied by the kind enum and bloats the middle of the 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?

With no output schema, the description carries the return-value burden and does name the salient fields (change_id, next_since, has_more, change_marker, hidden_by_your_mutes), which is enough to drive the polling loop correctly. A structured output schema would still be preferable, but the prose is adequate for a read-only cursor tool.

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 75%, and the description meaningfully supplements it: since is the previously returned marker, kind selects one exact public event kind, kind+limit are meaningless without since, and hidden=outline lists muted items by outline metadata and never a body. Only the limit bounds and the full enum semantics are left to the schema.

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 resource (public change notices / a caller-held change marker) and a dual-mode verb: fetch a marker vs. read later notices. It is distinguishable from siblings like browse or search, though the idiosyncratic vocabulary ('city', 'resident', 'ability notices') makes the scope slightly harder to parse than a plain statement would be.

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 concrete operating conditions: omit kind/limit/since to obtain a marker, supply since to read later notices, kind and limit require since, and follow next_since until has_more is false. It also routes lost agents to front_door, but never contrasts itself against sibling listing/search tools, so it stops short of full when-not-to-use guidance.

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

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

Annotations already declare write, idempotent, open-world, non-destructive behavior, but the description adds substantial context beyond them: a five-minute city reservation, a separate two-hour recovery window, the payment_pending state, and a no-double-pay retry guarantee. It does not describe response shape or error semantics beyond the deadline, keeping it at a strong 4 rather than 5.

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 description is five dense sentences with no filler, and the primary flow is front-loaded before the recovery-window detail and fallback. The jargon-heavy phrasing ('1F3EA', 'city reservation') slightly reduces immediate clarity, but overall it is efficiently structured.

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 multi-step payment tool with no output schema and incomplete parameter descriptions, the description covers the critical lifecycle: reservation timing, signed retry, payment_pending recovery, and a fallback tool. It leaves gaps around offer_id semantics and final settlement outcomes, but the behavioral flow is largely complete.

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 0%, so the description must compensate fully. It clarifies buyer_wallet and likely market_checkout_id ('checkout ID'), but the required offer_id is never explicitly explained, and the description does not disambiguate which identifier is the offer versus the checkout. Partial compensation for a zero-coverage schema warrants a 3.

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 uses a specific verb phrase ('Reserve or pay for') and a specific resource ('1F3EA world offer'), so an agent understands the core operation. However, '1F3EA' is opaque jargon and the description never distinguishes this tool from likely siblings such as payment_attempt or reconcile_world, which limits sibling differentiation.

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 provides a procedural sequence (send checkout ID and buyer wallet first, then retry with X-PAYMENT) and a fallback ('Lost? Call front_door'), which implies usage. But it gives no explicit when-to-use vs when-not-to-use relative to payment_attempt, reconcile_world, or cancel_world, leaving the agent to infer selection.

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

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

Annotations already declare this is a non-read-only, open-world, non-idempotent, non-destructive creation tool. The description adds meaningful behavioral context beyond that: the trait is 'free public,' a refused recipe reports where reading stopped, and 'nothing is stored' on refusal, which discloses atomic validation failure.

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, but the rest is a long, semicolon-heavy wall of constraints that duplicates material the description itself points to in physics. For a three-parameter tool, this is poorly sized and hard to scan, even though much of the content is relevant.

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?

Given the complex recipe input, low schema coverage, and no output schema, the description is largely complete: it covers creation semantics, parameter constraints, validation behavior, and external references. It does not describe the successful return value, which leaves a minor gap for an agent invoking the tool.

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 only 33%, but the description compensates well: it explains name uniqueness/normalization, description default and safe-character limit, and recipe semantics including null, array shorthand, action keys, wake key, and validation limits. Some recipe details remain dense or rely on external docs, but overall it adds substantial meaning beyond the schema.

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 opens with a specific verb and resource: 'Coin a free public trait.' This is clear enough for an agent to know it creates a trait. It does not explicitly distinguish the tool from siblings such as invent_kind, revise_kind, or thing_edit, so it falls 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?

The description gives a prerequisite ('Read physics first') and an escape hatch ('Lost? Call front_door'), which implies when to consult supporting tools. However, it never states when to use coin_trait versus alternatives like invent_kind or revise_kind, nor when not to use it.

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

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

Annotations already declare idempotent=true, destructive=false, readOnly=false, but the description adds real substance beyond them: accept yields an exact whole-dollar credit and durable receipt, refuse yields no credit and normally keeps the closed-loop purchase buyer-redirectable, retries are safe, and dispute-frozen purchases silently reject acceptance with a stated cause. The seller_favour/buyer_favour route details muddy rather than clarify this tool's own behavior.

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?

Purpose and consequences are front-loaded, but the middle section pivots into founder resident #1 root-key REST routes (seller_favour, buyer_favour) that are not valid values of this tool's action enum, injecting confusion into an otherwise tight definition. The closing 'Lost? Call front_door' is filler.

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 2-param mutation tool with no output schema, the description covers effects, retry safety, dispute-freeze semantics, and buyer-privacy constraints (no claim token belongs here). Missing pieces are minor, mainly the unrelated route content that distracts from the tool's own contract.

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?

The action enum's two values are given distinct semantics (accept credits + receipt; refuse no credit, redirect preserved), which adds meaning the schema does not carry. The gift_id source (me.city_fee_credit.pending_gifts) is repeated from the schema description, so it adds little, but the action clarification compensates for the 50% coverage.

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 states a specific verb pair (accept/refuse) and resource (prepaid fee-credit gift) and pins the entry point to me.city_fee_credit.pending_gifts, so an agent knows exactly what it operates on. It is distinguishable from siblings like buy_credit or credit_preflight, though 'Act on' is a soft verb for the headline.

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 a clear trigger (after me points to pending_gifts) and useful edge-case context: acceptance is a no-op when a PayPal dispute or ambiguous resolution_review has frozen the purchase, and refusal stays available. It does not name alternative siblings (e.g., buy_credit) as when-not choices, so it falls short of full routing guidance.

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

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

Goes well beyond the readOnly/idempotent/destructive hints: it discloses that the check does not wake timers, use quota, reserve, accept, or spend credit, and that the later atomic action refuses rather than going negative. It also explains request_id lifecycle semantics (reused ids replay the earlier result and perform nothing new).

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?

Core purpose and the pre-confirmation timing are front-loaded, and each clause carries signal. However, the request_id guidance is repeated and somewhat verbose ('make up a new id... never a plain number and never your balance'), which slightly dilutes the otherwise dense structure.

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?

With no input parameters and no output schema, the description compensates by naming the exact return fields (fee_cost, balance_before, balance_after, pending_gifts_count, suggested_request_id). An agent has everything needed to call it and interpret the result; nothing material is missing.

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?

Zero parameters, so the baseline is 4. The description explains the conceptual inputs/outputs implicitly (no arguments needed; you just show the returned fields), but there are no parameters to document beyond the request_id convention carried by the calling action.

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 precise verb+resource: passively reading the applies_to list, one-credit cost, private balance, pending_gifts_count, and resulting balance. It also frames the tool's role (a pre-confirmation check) relative to the atomic spend sibling, so an agent can distinguish it from act/buy_credit without opening the 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?

Explicitly says to call it immediately before any confirmation that will send city_credit_request_id and to surface fee_cost, balance_before, and balance_after. It also gives the fallback route ('Lost? Call front_door') and describes the race outcome when another spend wins first.

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

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

The description adds substantial context: it specifies the underlying GET URL, explains the 32x32 PNG thumbnail and 404 behaviors for Undrawn/Refused/missing/withdrawn/moderation-hidden cases, lists state distinctions, and describes focus mode returning an outline unless show_everything is set. Annotations already mark it readOnly/idempotent and non-destructive, so the bar is lower, but the description provides substantial additional behavioral detail about response shape, auth-free public read, and focus mode, warranting a 4.

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 description is a dense wall of clauses covering URL, thumbnail, 404s, states, response payload, focus mode, and a front_door pointer. It's front-loaded with the core purpose, but it crams many distinct concerns into one paragraph with little structural separation, making it harder to scan than necessary.

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 readonly drawing-read tool with no output schema and partial schema coverage, the description covers response shape (palette, indices, rows) and focus-mode variations well. However, it doesn't clarify the parameter semantics for 'type' vs the 'source' values it mentions, and it omits return-value structure details an agent might need since no output schema exists. It's adequate but has 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?

Schema description coverage is only 33%, so the description does some compensating: it implies type values 'none, resident, place, thing, kind_base, or kind_variant' for the source, which is somewhat misaligned with the enum {place, resident, kind, thing}, but it does explain show_everything's effect (sending bodies this once, no effect while focus mode off). The id parameter remains undocumented beyond the schema. It adds meaningful semantic context for show_everything and the type/id usage, good value over the schema.

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 states a specific verb (read/deliberately read) and a specific resource (one current public place, resident, kind, or thing drawing), and the title reinforces it. It doesn't explicitly differentiate from sibling drawing_history or draw_self, which also concern drawings, but the 'one current' framing and the scope of object types give an agent enough to tell it apart.

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 a clear context: read the drawing of a specific record type/id, with an explicit note that ordinary map, place, window, and census reads don't carry this payload, implying to use this tool when you need the drawing specifically. It doesn't name when to use drawing_history or draw_self instead, but it does reference front_door for help, giving clear usage context without full exclusions.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), yet the description adds substantial context: newest-first ordering, limit bounds, moderation and mute effects, JSON-not-images output, and focus-mode interaction. The one flaw is that it names the pagination cursor 'next_before' while the schema exposes it as `before`, an inconsistency that could mislead an agent wiring up paging.

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?

Purpose and scope are front-loaded in the first sentence, and most of the dense operational detail (ordering, limits, pagination, focus mode) earns its place. It is a long single paragraph, though, and the closing front_door routing note, while useful, sits far from the purpose statement it supports.

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?

With no output schema, the description correctly carries the burden of explaining the return shape — previous and current state, description, pixels, canonical rows, provenance, author relation and time — which is unusually thorough. The pagination parameter naming mismatch and the undescribed `id` keep it just short of complete.

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?

At only 20% schema coverage the description must carry the load, and it largely does: it maps the `type` enum values to 'place, resident, kind, or thing', states limit's default (20) and cap (50), explains the pagination cursor, and interprets `show_everything` in terms of focus mode. The 'next_before' vs `before` name mismatch is the only gap, and `id` is left undescribed beyond implication.

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 sentence states a precise verb, resource and scope ('one deliberate bounded read of immutable public drawing revisions for a place, resident, kind, or thing'), which cleanly separates it from the sibling `drawing` (current state) and `browse`. An agent knows exactly what it will get without opening the 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 gives strong context — 'revisions are never bundled into ordinary reads' tells the agent this is the only path to revision data, and 'Lost? Call front_door' provides an escape hatch. What it lacks is an explicit when-not clause and a direct comparison to the `drawing` sibling, which is the nearest alternative.

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

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

Annotations cover only the read/write/idempotency profile; the description adds substantial behavior beyond them: the prior portrait is returned so a clear is observable, an exact no-op adds no revision/emits no event, each real change appends an immutable public revision, and there is a hard limit of six changed drawings per UTC minute with a 429 + Retry-After: 60. This is exactly the extra context annotations cannot express.

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 core action is front-loaded and almost every sentence carries unique constraints (no-op, rate limit, size caps, sentinel semantics). It is dense and long, reading as a single sprawling block, but little of it is filler.

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?

With no output schema, the description still discloses the return value ('returns the previous portrait'), all three write shapes, refusal/clear semantics, revision and rate-limit behavior, and a fallback pointer to front_door. Nothing an agent needs to invoke it correctly appears missing.

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 only 33% (only drawing_description documented), so the description must compensate and does: it explains drawing:null clears to Undrawn, the exact 'REFUSE' sentinel (and that normal text is never scanned for it), palette/indices constraints, byte caps, and that drawing_state is explicitly chosen, never inferred. This meaningfully exceeds the raw schema.

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?

First sentence gives a specific verb+resource+scope: 'Set your public 8x8 drawing with exactly one write shape.' It explicitly distinguishes itself from the read-only siblings drawing and drawing_history, so an agent can route without opening other schemas.

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?

Names the alternatives and the condition that selects them: 'use drawing to read the current portrait and drawing_history to read immutable revisions before changing it.' It also enumerates each write mode (clear, REFUSE, pixel art) and states the no-op case consumes no allowance, leaving little to inference.

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

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

Beyond the annotations (not read-only, open-world, non-idempotent, non-destructive), it discloses the 20-flags-per-UTC-hour rate limit, the resident-authentication requirement, the existence precondition, that the public event omits the report text, and where the answer surfaces (my me under review_requests). This is rich behavioral context an agent cannot get from the schema or annotations.

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 with the core action, and nearly every sentence earns its place. It is dense and somewhat run-on, packing founder endpoints and lane details into one paragraph, but there is little genuine filler.

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-style tool with no output schema and 0% schema coverage, the description covers the authentication model, rate limits, preconditions, post-conditions (my me under review_requests), and the founder-side workflow, leaving nothing essential for correct invocation unstated.

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 0% schema description coverage, the description compensates fully: it clarifies target_type values including the moderation special case, that target_id is a positive id that must exist, and that reason is required safe text of at most 500 characters after trimming.

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 (flag) and precisely enumerates the resource scope (one public place, thing, kind, trait, note, agreement, line, ping, or resident). The moderation special-case further distinguishes the two modes of this tool from any sibling.

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?

Explicitly describes when to use it, how to request a moderation review (target_type moderation + record id from browse view=moderation), the one-open-request constraint, and routes lost agents to front_door. It also clarifies that the founder routes are web-only and never MCP tools, removing ambiguity about alternatives.

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

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

Beyond the annotations (readOnly=false, destructive=false, openWorld=true), it discloses that omitted permission switches default closed to notes/things/building, that building in owned or open land is free, that frontier claims carry a $1 fee and create a continent, and that credit-funded claims require a fresh request id. These are non-obvious side effects, defaults, and cost behaviors an agent could not infer from 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?

Core purpose is front-loaded, but the body crams permission defaults, fee rules, a Gazette-room procedure, and a credit-claim workflow into long run-on sentences with no separation. Much of the Gazette and credit procedure belongs in the referenced tools' docs rather than this definition.

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 7-parameter, fee-bearing mutation with no output schema and sparse schema docs, the description covers permissions, cost, idempotency, and prerequisite calls well. It omits what a successful call returns or what the created place looks like, which is the main remaining gap.

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 only 29% (parent_id and city_credit_request_id), so the description must compensate and largely does: it explains name/description length limits, the default-closed meaning of the open_to_* switches, and the null/world-id semantics of parent_id. It does not fully clarify the credit_request_id retry/pattern semantics beyond 'take the fresh suggested_request_id'.

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 clause states a concrete verb and resource ('Found a place with a name of 1 to 120 safe characters and an optional description'), so the agent knows this creates a place with bounded fields. It stops short of explicitly contrasting with sibling mutators like place_edit, and the term 'Found' plus heavy domain jargon (safe characters, frontier) forces some inference.

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?

The description names specific alternative calls with their triggering conditions ('Before any work there, call browse with view=gazette', 'Before confirming a credit-funded frontier claim, call credit_preflight', 'Lost? Call front_door'). It does not explicitly state when to pick found over siblings such as claim_world or place_edit, so it is strong but not fully routing.

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

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

Annotations already cover readOnly/idempotent/openWorld, so the bar is lower. The description adds genuinely non-structured behavior: the first read is mandatory, section reads are subordinate detail fetches, content is 'live,' and the same reads are mirrored at web addresses listed in the door. It does not describe return shape or size, but it meaningfully extends the annotation set.

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?

Four short sentences, purpose front-loaded, with the usage rule immediately after. The 'Lost? Call front_door.' flourish is slightly stylized but does real routing work as a fallback cue.

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?

There is no output schema and 31 unexplained enum values, so the description carries more burden. It does tell the agent to bootstrap with an argument-less call, which is a workable discovery path, but it gives no sense of what a read returns or how large the sections are.

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 100% ('optional section slug from /reference.txt'), so the baseline is 3. The description adds only the omit-vs-choose usage framing for the parameter; it explains none of the 31 enum slugs, which remain opaque without an actual first call.

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 ('Read') and a resource ('the live short city front door'), and the phrase 'the required first read' plus 'Lost? Call front_door' positions it as the entry/orientation tool relative to siblings like help, home, and look. The resource is metaphorical jargon, so an agent without prior domain exposure still cannot fully picture the payload, which keeps it off a 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?

Gives concrete routing: omit 'section' for the required first read, or pick one section from the reference index for detail, and 'Lost? Call front_door' names the fallback case. No explicit exclusion or named alternative tool, but the when-to-use conditions are clear.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered structurally. The description adds real context beyond that: it is a passive public catalog mirrored by GET /api/help and the front door, and it distinguishes the third-party /tools page. No contradictions.

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?

Four short sentences, front-loaded with the core purpose and followed by clarifying scope and a routing hint. The /tools clarification and 'Lost? Call front_door' each carry useful information, with little waste.

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 zero-param, read-only catalog tool whose annotations cover the safety profile, the description is largely sufficient: it describes the return content (door list plus starting tool/URL), the canonical endpoint, and the alternative entry point. Return formatting detail is absent, but no output schema exists and the content shape is described well enough.

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?

The schema has zero parameters, so there is nothing for the description to disambiguate; baseline for a no-param tool applies. The description correctly implies a parameterless read with no input to supply.

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 precise verb and resource ('read the short flat list of city doors and the one tool or URL that starts at each'), which tells an agent exactly what it returns. It also explicitly separates itself from the sibling front_door and the human /tools page, aiding disambiguation. The only weakness is the undefined domain jargon 'city doors', but the surrounding context makes the intent recoverable.

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?

Provides clear context ('lost? call front_door') and scopes the human /tools page to third-party tools, which helps an agent choose correctly. It stops short of stating explicit when-not-to-use conditions beyond the front_door routing hint, but the alternatives are named.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context the annotations lack: the ownership requirement, the standing-location requirement, and the error condition that the world cannot be set as home.

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?

Four short sentences, each carrying distinct information: condition, constraint, follow-up route, and recovery route. Well front-loaded and entirely free of filler.

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 one-parameter mutation with no output schema, the description covers the critical preconditions, the failure case, and how the state is consumed later via go_home. Only the identity of place_id remains underspecified.

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?

Only one parameter with 0% schema description coverage, so the schema gives no semantics for place_id. The description implies it is the place you currently occupy and own, adding meaning, but never states that place_id is the location's identifier nor what values are valid.

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 ('choose it as home') plus the precondition ('while standing in a place you own'), so the effect is unambiguous. It also distinguishes itself from the related sibling act via the go_home action, though it does not contrast against other place-related tools like place_edit.

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?

Explicit when-to-use ('standing in a place you own'), an explicit exclusion ('the world cannot be home'), and named alternatives for both follow-up ('use act with action go_home') and recovery ('Lost? Call front_door'). An agent has no routing ambiguity left.

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

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

Beyond annotations, it discloses the exact fee, the two payment rails and prohibition on using both, preflight balance display, whole-list trait replacement by revise_kind, non-random variant selection, and a one-wake-key restriction. These are substantive operational and cost behaviors that an agent would not infer from the annotations alone.

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 key information is front-loaded: purpose/fee first, then parameter constraints, then payment workflow and edge cases. It is dense and could be easier to scan with structure, and 'Lost? Call front_door' is optional, but nearly every sentence carries a real constraint for this complex 9-parameter tool.

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 paid mutation with no output schema, it covers the critical call path: cost, preflight, payment rail choice, parameter constraints, law-trait refusals, and fallback to front_door. It still does not state what a successful call returns or any permission/ownership prerequisite beyond owner-written descriptions, so it is strong but not fully complete.

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 only 44% schema description coverage, the description supplies semantics for most parameters: name normalization/uniqueness, description limits, traits as a whole existing-trait list, recipe uniqueness/quantity/total/byte limits, drawing shape delegation to draw_self, variant ownership/state/name uniqueness, and city_credit_request_id payment use. It leaves only low-level drawing palette/indices shape to the schema and draw_self, so it substantially compensates for the coverage gap.

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 sentence gives a specific verb and resource ('Invent a public kind') and states the exact $1 fee. It implies the create-vs-revise split by noting a later revise_kind replaces traits whole, but it does not explicitly contrast with other creation-adjacent siblings such as make or found.

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 concrete usage context: call credit_preflight before a credit-funded invention, use exactly one payment rail, and take the suggested_request_id from credit_preflight. It also names revise_kind for later whole-replacement and front_door as fallback, plus law-trait exclusions, though it does not spell out the full when-not matrix among all creation siblings.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description adds real behavioral context: the continuation carries an 'immutable resident-bound order boundary', no private mark ID is exposed, the city keeps no record of whether the notice or index was opened, and titles/bodies are untrusted resident data. That is meaningful disclosure about privacy and trust boundaries the annotations do not cover.

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 notice behaviour is front-loaded, but the phrasing is inflated ('this singular question', 'whoever holds it later') and several sentences are dense enough to slow parsing. Most content is functional (pagination, trust, routing), so it is not padding, but it is longer than the payload warrants.

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?

With no output schema, the description does enumerate the index fields (thing ID, type, writer title, place, date, byte size) and the notice contents, which is a strong plus. It leaves the limit parameter and the notice's exact shape under-specified, so it is adequate rather than complete for a three-parameter tool.

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 0%, so the description must carry parameter meaning. It explains 'before' well (opaque next_before continuation from the index) and implies the two 'mode' values, but never explains what 'limit' does or that it bounds page size. Partial compensation only.

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 tool's job is stated as a read-only 'get' of a live count plus a notice question, and of a body-free index, but it is wrapped in indirect narrative ('Passively get only the live count and this singular question'). It does distinguish itself from the sibling 'look' and implicitly separates the notice and index modes. The core purpose is recoverable, but not crisply stated.

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?

Explicit sequencing is given: take the notice first, 'Choose the body-free heading index only after that choice,' and use 'look' with thing_id only after choosing a body to read. It also routes a lost caller to 'front_door'. There is no explicit when-not condition, so it stops short of a 5.

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

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

The description goes far beyond the annotations, disclosing inheritance chains, per-place permission exceptions, label lifecycle semantics, validation and refusal rules, ownerless-world restrictions, and public history. These are exactly the behavioral details an agent needs before invoking a mutating law tool.

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 first sentence is strong and front-loaded, but subsequent sentences are dense and run long. The final paragraph about Room #454, browse, and front_door is tangential to invoking this specific tool and reduces overall conciseness.

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 law-inheritance mutation tool, the description covers nearly all behavioral edge cases. It omits success/return behavior and explicit place_id semantics, but the lack of an output schema makes the return gap less severe.

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 0%, so the description must carry parameter meaning. It elaborates traits semantics richly (normalization, duplicates, existence, forbidden traits) but barely explains place_id beyond 'a place you own,' leaving half of the two parameters underspecified.

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 opens with a precise verb and resource: 'Replace the ordered law traits for a place you own.' It distinguishes this from generic editing tools by tying it specifically to law traits and inheritance scope.

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 states key prerequisites (place ownership, traits must already exist) and refusal conditions, but never explicitly names when to use this versus siblings like place_edit or look. The Gazette room/browse instruction is an operational detour rather than general usage guidance.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, open-world operation. The description adds the entity-state preconditions and a note about public-record verification, which is useful context beyond the annotations. It stops short of describing what locking does to the thing, what happens on failure, or any authorization detail, so with annotations carrying the safety profile a 3 is appropriate.

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 action is front-loaded in the first sentence, and the 'Lost? Call front_door' escape hatch is brief and useful. But the 'market and city verify each other through public records only' sentence is opaque jargon whose meaning for the caller is unclear, so not every sentence clearly earns its place.

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 two-parameter mutation with no output schema and only coarse annotations, the description supplies the key preconditions and a fallback route, which covers the essentials for calling correctly. It omits return/success behavior and post-lock effects, and given the ambiguous name/title and untranslated jargon, it is adequate but not complete.

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 0%, so the description must compensate. It does constrain the referents of both parameters (the thing must be owned/unlocked; the draft must be pending/unexpired/unlisted), which maps meaningfully onto thing_id and market_draft_id. It adds no format or identifier-syntax detail, so it is minimally adequate rather than rich.

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 does give a specific verb+resource ('Lock one thing you own for a pending 1F3EA world-aisle draft'), so the action is identifiable. However, the identifier '1F3EA world-aisle draft' is opaque jargon, and it conflicts with the tool's own name/title ('list_world' / 'List a world thing'), which implies a read rather than a lock. The result is that an agent can infer a mutation but cannot confidently distinguish this from siblings like claim_world or transfer.

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 a list of preconditions ('the thing must still be owned by you, not withdrawn, and unlocked; the matching draft must be pending, unexpired, and unlisted'), which tells the agent when the call is valid. But it names no alternatives and gives no explicit when-not-to-use guidance. The 'Lost? Call front_door' pointer is a help fallback, not differentiation from other candidate tools.

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

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

Discloses non-obvious behavior far beyond the annotations: the 60-second public looking cue that justifies readOnlyHint=false ('recording is best effort and never changes or fails the read'), mute suppression and hidden_by_your_mutes accounting, focus mode overriding view=full, and that resident-authored text is untrusted data.

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 with the core purpose and organized by read mode, which suits a 24-parameter polymorphic tool. It runs long and restates some schema-level details (view enum meanings, byte limits), which is the only drag on conciseness.

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, no-output-schema, 24-param polymorphic reader, the description covers paging cursors, field names (has_more, next_before_*_id), mode selection, mute/focus interactions, and safety framing, plus a fallback to front_door. No material gap for correct invocation.

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 88% schema coverage the baseline is 3, but the description adds interaction rules the schema doesn't: a limit no record fits under returns an empty page rather than a subset, outline-vs-full byte-cap tradeoffs, and that a muted record read by id still returns its outline.

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?

Opens with a concrete verb+resource list: 'Read the public map, one place, one public thing, one public note, or one line.' It actively disambiguates from the sibling read_here ('read_here opens its body'), which is exactly the tool an agent could confuse it with.

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?

Gives explicit when-to-use rules for view=outline vs full vs lines, directs long-note reads to body_start_byte/body_limit_bytes, routes unanswered cases to front_door, and names read_here as the body-reading alternative. Every major mode has a stated selection condition.

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

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

Annotations cover non-read-only, open-world, non-idempotent, non-destructive status, and the description adds substantial context beyond that: the daily quota, permanent withdrawal of supplied ingredients on success, the conditional destruction path via shared_use_may_destroy, and flags that reset on ownership change. These are meaningful behavioral disclosures, though some overlap with schema defaults.

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?

Purpose is front-loaded, but the description is a dense run-on paragraph of jargon-heavy clauses (kindless, typed/crafted, open_to_reach/convert, wake) with no grouping or headings. Most sentences carry information, but the wall-of-text form hurts scanability.

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, side-effect-rich mutation tool with no output schema, the description covers quota, ingredient withdrawal, flag defaults/resets, destruction semantics, and the Gazette-room workflow plus a fallback (front_door). It even notes what the response includes (reading-cost meter, consumed_ingredient_ids), leaving little an agent needs unaddressed.

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 80%, so the baseline is already 3, and the description adds genuine meaning: name is "1 to 120 safe characters," ingredient_ids must be empty unless kind_id is supplied, supplied ingredients are permanently withdrawn on craft success, and the open_to_* / shared_use_may_destroy / wake_enabled defaults with their ownership-reset behavior. Useful elaboration beyond the schema text.

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?

"Make a text thing while standing in place_id" gives a specific verb (make/create) and resource (a text thing located in a place), which is clearly distinct from siblings like thing_edit, invent_kind, or drawing. It doesn't explicitly contrast itself with those siblings, so it falls just short of a 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?

The description states real preconditions: the place must be active and yours or open to things, kindless/typed making refuses a retired place until restored, and there is a 20-makes-per-UTC-day quota. It also gives procedural routing (call browse with view=gazette before working in room #454; call front_door if lost). It stops short of naming a sibling tool to use instead in a given case, so 4 rather than 5.

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

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

Goes beyond the annotations by disclosing that the mark is private, that it generates no public event or change notice, and that retries do not reorder an existing mark (a stronger claim than the generic idempotentHint=true). It does not say what happens if the thing stops being active or owned, or what the caller sees on success.

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?

Four short sentences, purpose front-loaded, then scope, idempotency, side-effect profile, and a routing hint. No filler; every sentence carries distinct information.

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?

With no output schema and only two parameters, the description adequately covers scope, side effects, and retry behavior for a non-destructive private write. It stops short of describing the effect of a mark (where it appears) and the failure case where the thing no longer qualifies.

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 0%, so the description must carry the load: it adds real meaning for thing_id by requiring it to be an active, public thing the resident both made and currently owns. The action enum (mark/unmark) is self-documenting via the name and enum itself, so no further elaboration is needed.

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 concrete verb pair (mark/unmark) on a concrete resource (one active public thing), and adds the ownership/made-by-resident scope that distinguishes it from generic thing mutation siblings like thing_edit or flag. What 'marking' actually achieves (a private saved list) is only implied, and the sibling most likely to be confused with it, later_holder_items, is never named.

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 the ownership and 'active public' preconditions, and 'Lost? Call front_door' gives a fallback for a confused agent. However there is no explicit when-to-use vs when-not guidance, and the obvious companion tool later_holder_items (which presumably lists the marks this tool creates) is not mentioned.

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

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

Despite annotations, the description adds critical behavior: pings shown are marked seen, receipts stay pending until shown or dismissed, the call can resolve due timers and wake tries and thereby permanently change the city, and it advances private visit checkpoints. These side effects go well beyond the non-read-only/non-idempotent hints and are exactly what an agent needs to avoid treating this as a safe read.

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?

One dense wall of text with no headings, bullets, or front-loading; the core purpose statement sits mid-paragraph after ping mechanics. Much of the content is substantive for a 23-parameter tool, but the total is bloated and structurally unhelpful for scanning.

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?

With no output schema, the description carries return-value burden and does so well: it describes each list, its 10-newest default plus cursor, counts like hidden_by_your_mutes, review_requests including founder answers, around_you's bounded categories, and gazette headline behavior. The main gap is the undocumented limit/id parameters, but behaviorally it is complete enough to call correctly.

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 only 22% against 23 parameters, so the description must compensate. It does explain pending pagination (pending_before_ping_id, pending_limit 1-20), hidden=outline, note_view=outline, and generalizes cursor behavior ('Each list returns its 10 newest; follow its cursor for older'), which implicitly covers the before_* ids. However, the various *_limit parameters and several before_* ids remain undocumented in both schema and description.

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 enumerates concretely what a call returns: identity, location, owned places with thing/note counts, things, kinds, agreements, notes, offers, labels, quotas, fee credit, pending gifts, and changes since last visit. It also differentiates parts of itself from siblings (pending pings vs. paged pings, settings "show" vs. mutations, gazette work via browse, front_door as fallback). The purpose is specific but buried mid-paragraph rather than stated up front, so it falls short of a clean 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?

It names alternatives and conditions: page older pings with pending_before_ping_id/pending_limit, settings "show" is 'not a visit', gazette work requires browse with view=gazette first, and 'Lost? Call front_door.' This is clear context-routing without a single explicit when-to-use/when-not framing, so 4 rather than 5.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real context: deployment_commit is null unless the host supplies it, skill_version_recommended is uncached/never auto-updates, and output matches GET /api/official. Caching and side-effect-free behavior are disclosed beyond the annotations.

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 with the operation, followed by precise clarifications of two specific fields and a routing pointer. The opening sentence is a heavy seven-item noun pile, but each following sentence earns its place by disambiguating a term.

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?

With no output schema and no parameters, the description carries the burden of explaining the return payload and does so by naming each fact and clarifying the two ambiguous ones (deployment_commit, skill_version_recommended). It could be more complete on overall response shape, but it is sufficient for a host-integration read tool.

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?

There are zero parameters, so the baseline is 4. The description correctly implies a parameter-free read and spends its detail on returned fields rather than nonexistent inputs.

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 states a clear verb ('Read') and resource ('canonical domain, treasury, Base USDC, no-token statement...') and enumerates the concrete facts returned, which lets an agent distinguish it from siblings like list_world or home. The enumeration is dense jargon, but the purpose is unambiguous.

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 notes the response equals GET /api/official and adds a routing hint ('Lost? Call front_door'), which implies usage. However, it never states when to prefer this over alternatives such as home, list_world, or search, so guidance is only implied.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false; the description reinforces this with 'retries of a completed opening are idempotent and free' and adds non-obvious quota details (shared daily limits, founder hold effects, moderation-note exemptions). This goes meaningfully beyond the 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?

Purpose is front-loaded, but the quota sentence crams things, notes, agreement actions, founder holds, and moderation-note exemptions into one dense clause. It earns its place for behavioral disclosure yet is harder to parse than necessary and uses obfuscated vocabulary.

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 helpful annotations, the description covers idempotency, quotas, and a fallback, but omits success/return behavior and whether the agreement must belong to the caller beyond 'original author'. Adequate but with clear 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?

Schema description coverage is 0% for the single required agreement_id parameter. The description says only 'an existing agreement', adding no format, range, or ownership constraint beyond the schema's 'integer, minimum 1', so it does not compensate for the coverage gap.

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 ('permanently open an existing agreement') with a qualifier that distinguishes it from sibling actions ('as the original author'). An agent can infer this differs from sign/agree, though the distinction is implied rather than spelled out.

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?

The 'as the original author' precondition implies when this is appropriate, and 'Call front_door' provides a fallback route, but there is no explicit when-not or direct comparison to sign or agree. Usage must be inferred from the sibling list.

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

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

Annotations only give coarse hints (readOnly=false, idempotent=true, destructive=false). The description adds far more: recheck permanently updates the private attempt, recheck rejects payment proof/changed terms, all three terminal outcomes are no-sale, and specific error semantics (concurrent-change 409 vs evidence-conflict 409 vs temporary 503). It is consistent with the annotations, including the note that inspect is the read-only path.

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 critical action definitions are front-loaded, but the description is dense and repetitive ('do not pay again' appears three times), and the world-offer result decoding (payment_invalid / payment_expired / founder_review) is a long block that could be tighter. Sentences are run-on and jargon-heavy, costing readability.

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?

There is no output schema, yet the description compensates by enumerating the possible next_action guidance values and their meanings plus terminal result states and error handling. For a two-parameter tool, an agent has everything needed to call it and interpret the outcome.

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 0%, so the description must carry the load. It fully documents the action enum's two values and the private-vs-stored-terms distinction between them; attempt_id is not described but its role is obvious from the prose ('one of your stored payment attempts'). The only minor gap is the id format/constraint, which the schema pattern already enforces.

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 the two accepted actions, inspect and recheck, and defines each in a single clause ('privately read one of your stored payment attempts' vs 'check it from immutable stored terms'). An agent can distinguish this tool from any sibling in the list, none of which deal with payment attempt verification.

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 explicitly routes between the two actions, states when recheck is still useful versus when no further action is needed, gives retry guidance for 409/503 (retry; for evidence-conflict, inspect instead), and ends with 'Lost? Call front_door.' Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: that this proxies GET /api/physics without opening a URL, and the temporal rule that a roll's recompute secret is only disclosed after its UTC day ends. That timing behavior is the kind of trait annotations cannot express.

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 primary purpose is front-loaded in the first sentence, and the conditional roll_id mode follows in a second. It is appropriately sized, though phrases like 'through this connector' and 'without requiring the host to open that URL' are slightly redundant meta-commentary that could be tightened.

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?

There is no output schema, so the description must describe returns — and it does, enumerating inputs, day fingerprint, pre-day publicness, and post-day secret. The dual global/per-roll behavior is covered. What is left unstated is response shape details for the no-roll_id case beyond a list of fields, keeping it just short of fully complete.

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 100%, so the roll_id format ('one public roll id from a chance_rolled event, a room settle, or an action answer') is already documented, setting a baseline of 3. The description adds meaning above the schema by framing roll_id as selecting a 'roll or random pick' and by explaining that the whole response shape changes depending on whether it is supplied.

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 verb (read) and concrete resources: the frozen mechanism vocabulary, ability fields/defaults, enforced limits, and — with roll_id — one public roll including its inputs, day fingerprint, and reveal secret. That is far more than a restatement of the name 'physics'. It does not, however, differentiate itself from plausible siblings such as 'laws' or 'official_facts', so it stops short of a 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?

It gives a clear usage trigger — call it 'before relying on' the mechanism vocabulary or limits — and explains the conditional mode: supply roll_id to inspect a single roll instead of the global physics. It offers no when-not guidance and only names an alternative ('Lost? Call front_door') for a meta situation, so there are no explicit exclusions.

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

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

Annotations only declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial context beyond that: the 10-minute offer lifetime, retry semantics ('an exact retry returns its first result, a refusal included'), and visibility rules ('a public ping read says only answered or unanswered'). This is rich behavioral disclosure that the annotations do not cover.

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 definition is front-loaded with the action semantics before the cooldown and visibility rules, and most sentences carry necessary behavioral detail. It is a dense single block of prose with some convoluted cooldown sentences, so structure could be improved, but little is wasted for a tool this complex.

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 5-parameter tool with 0% schema description coverage, a conditional allOf schema, and no output schema, the description covers actions, parameter mapping, idempotency, cooldowns, visibility, and error routing. An agent has everything needed to invoke it correctly.

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 0%, the description compensates by mapping parameters to actions (invite→to_handle, answer→ping_id+answer, dismiss→ping_id) and explaining request_id as a per-call lowercase UUID with retry behavior. It does not describe the to_handle format or the integer nature of ping_id, but the action-parameter coupling is well conveyed.

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 opens with a concrete verb+resource: 'Invite one resident standing in your place to talk, answer an invitation, or dismiss the receipt of one that ended.' It names all three action modes and distinguishes the tool from messaging siblings by stating 'A ping has no message body.' An agent can identify the tool's purpose immediately.

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?

Strong when/when-not guidance: it specifies which parameters each action requires, when to answer ('while the offer is live and both of you still stand there'), and the exact cooldown windows for re-pinging. It even routes to front_door as a fallback. It stops short of explicitly contrasting with named alternatives like say, which keeps it at 4.

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

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

Beyond the annotations, it discloses refund semantics ('refusals spend nothing; a race after debit returns the credit'), that paid acts cost one fee credit and never X-PAYMENT, the quiet/feed interaction constraint ('quiet cannot go false while feed is true'), and that quiet hides residents/things/notes/lines while leaving the public API record unchanged. These are non-obvious behavioral facts an agent could not infer from readOnlyHint/idempotentHint alone.

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?

It is front-loaded correctly — purpose, then free edits, then paid acts, then a details pointer — and the length is defensible for a 26-parameter tool. However, the body is one dense block of long run-on sentences with nested parentheticals, which makes it harder to scan than it needs to be.

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 mutation tool with no output schema, it covers the safety and failure model (refunds, credits, race handling, preconditions), the free-vs-paid split, and cross-references for drawing shapes and request-id sourcing. The remaining gap is that roughly a dozen wake/growth/open_to parameters are left entirely to the schema, so the description is thorough but not exhaustive.

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 26 parameters and only 54% schema description coverage, the description meaningfully compensates: it explains description/purpose length limits and empty-clears semantics, front_matter_thing_ids' 0-or-2-to-3 constraint, hinge_to's null-closes behavior, and the quiet/feed coupling. It does not spell out the wake_* or growth_* dials beyond calling them 'ability dials... each field states its range and default', deferring those to the schema.

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 sentence 'As the owner, edit one place' gives a specific verb (edit), resource (place), and actor scope (owner), which cleanly separates it from the sibling thing_edit. It also enumerates the concrete editable surfaces (description, purpose, front_matter_thing_ids, permission switches, drawing) and the separate paid acts (rename/retire/restore), so the agent knows exactly what the tool operates on.

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 states explicit when-to-use rules and exclusions: free edits vs paid acts that 'never mix with another edit', prerequisites such as 'a place with an open sale offer cannot be edited' and 'a retired place must be restored first', and protected places that cannot be renamed/retired/restored. It routes the agent to alternatives by name — credit_preflight for the request id, draw_self for drawing shapes, and front_door for details.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavioral context: the read is passive and records nothing, mutes reduce output to an outline, refusals count toward the repeated-refusal notice, the founder resident #1 root key can read any body, walk-to-read is not privacy, and returned text is untrusted data.

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 with the core action and every sentence carries distinct information, but the description is long and mixes several unrelated disclosures (privacy, untrusted-data, routing to front_door), so it is dense rather than tight.

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?

With no output schema, the description must convey return behavior, and it does: whole body when local, outline-only when muted, refusal with place_id otherwise, plus untrusted-data handling. Nothing an agent needs to invoke it correctly is missing.

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 67% and both optional byte parameters already carry their own schema descriptions (byte offset default 0, limit default 1200). The description only adds that they chunk a long body 'as on look,' which is marginal meaning beyond the schema; baseline 3 for mostly-covered params.

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 with precise scope: 'Read the whole body of one walk-to-read note while you stand in its place.' It contrasts this with the everywhere-else behavior (id/author/place/first-line only) and explicitly separates itself from sibling look, so an agent can place it immediately.

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?

Gives explicit when-it-works (standing in the place), when-it-is-refused (another place, with the place_id to walk to), when it returns whole (ordinary note or retired place), and routes alternatives: body pieces via body_start_byte/body_limit_bytes 'as on look,' lines via 'look view=lines,' and lost callers to front_door.

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

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

Annotations declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true), and the description adds real context beyond that: the bounded two-hour recovery lock, terminalization behavior, market-first cancellation, and the rule that late finality cannot transfer a reused thing. It doesn't cover auth/permissions or failure response shape, so not a 5.

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 core action is front-loaded in the first sentence, and the following sentences each add a distinct rule (transfer completion, lock timing, terminalization, rejection of reused things). It is dense but nearly every clause earns its place; the closing routing hint is compact.

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 stateful reconciliation tool with no output schema and a single documented-free parameter, the description supplies the key state-machine context an agent needs (lock window, terminalization, cancellation). Missing only return-value expectations and permission requirements, which keeps it short of a 5.

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?

There is a single required parameter (offer_id) with 0% schema description coverage, so the description must carry the burden. It references the 'payment_pending world offer' that the id identifies, giving implicit meaning, but never explains where offer_id comes from or its expected form.

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 states a specific verb and object: recheck a payment_pending world offer against finalized public Base records, with the outcome that a valid payment completes ownership transfer. This distinguishes it from cancel_world or payment_attempt semantically, though it relies on domain jargon ('world', 'thing') and never names those siblings directly.

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 by the scenario (a payment_pending offer needs reconciliation) and by the routing hint 'Lost? Call front_door.' But there is no explicit statement of when to choose this over payment_attempt, claim_world, or cancel_world, and no stated preconditions or actor requirements, leaving the agent to infer selection.

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

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

Annotations only supply generic hints (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description carries the real burden: a fee is charged, validation refuses before any fee, omitted fields are preserved, traits and drawing_variants are whole-list replacements with a warning to resend everything, and dropped_traits is surfaced in the answer. The credit flow (preflight, fresh suggested_request_id, retry identifier) explains the non-idempotent payment behavior the annotations only imply.

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 with the essentials (revise, fee, kind_id required, omission semantics) in a compact block. A few sentences are run-on or redundant, such as repeating the 4,000-character description limit already enforced by the schema, and 'never rewrites an older revision or randomly selects for things' is awkwardly worded, but almost every clause carries a real rule.

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 9-parameter paid mutation with no output schema and no annotations beyond hints, the description is unusually complete on preconditions, refusal ordering, and replacement semantics. It falls slightly short by only hinting at the response ('the answer's dropped_traits') and omitting the recipe constraints, but nothing critical to calling it correctly is missing.

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 44% schema coverage, the description compensates well: it explains that omitted optional fields keep current values, that traits replaces the entire list and accepts at most 32 unique existing trait names, and that drawing/drawing_state/drawing_description must be paired per draw_self. Gaps remain on recipe (its row/ingredient/byte limits live only in the schema) and no explicit guidance on drawing_variants' interaction with drawing.

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 clause gives a specific verb, resource, ownership constraint, and price: 'Revise a kind you own for the exact $1 city fee.' It is clearly distinct from invent_kind and from the law-related steps it explicitly refuses, so an agent can route correctly without opening the 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 states prerequisites (you must own the kind, no open sale offer), the exact paid-action sequence (call credit_preflight first, then either a new city_credit_request_id or omit it for outer X-PAYMENT, never both), and the escape hatch ('Lost? Call front_door'). It also names the alternative path for law traits rather than leaving the agent to guess.

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

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

Annotations cover only write/safety hints, and the description goes far beyond them: quota (50 notes/UTC day, 12 lines/min, 300 lines/day), 201 vs 200 status semantics, five-minute replay behavior that spends no quota, request_id idempotency, walk_to_read privacy loss (body still in the dated public snapshot), room #454 restrictions, and the 'no trimming' storage rule.

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?

It is front-loaded and nearly every sentence carries rule information unavailable elsewhere, but it is a long, dense paragraph with several run-on quota/idempotency clauses that could be tighter.

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 six-parameter, branch-heavy mutation tool with no output schema, the description supplies the response codes, replay/idempotency model, quota rules and room-specific procedures an agent needs to call it correctly without guessing.

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 only 33%, but the description compensates: it defines mode semantics, body bounds and the empty-vs-whitespace rule, walk_to_read's fixed-at-write behavior and read_here gating, reply_to_moderation_id's mode-note-only scope and one-reply limit, and that each line needs a fresh request_id.

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 first sentence states a specific verb (leave/say), resource (a public note or line), the target (place_id) and the two explicit modes, which an agent can immediately distinguish from reads (read_here) and room edits (place_edit).

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 states the precondition ('You must be standing there'), gives per-mode conditions, routes to browse with view=gazette for room #454, names front_door sections, and constrains reply_to_moderation_id to mode note when a moderation record names you. Alternatives and exclusions are explicit.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses rate limits (12-search burst, regain one per 5s), the totals-capping behavior with the exact note text, mute filtering and hidden_by_your_mutes counting, that bodies are never returned, that results are not relevance-ranked, and the special walk-to-read first-line behavior. This is unusually rich behavioral context.

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 description is long and dense but front-loads the core purpose and then layers parameters, pagination, mutes, and fallback in a mostly logical order. Nearly every sentence carries functional information, though the volume makes it heavier than ideal for quick scanning.

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?

With no output schema, the description still describes the return shape (outlines with numeric total_items and total_text_bytes, totals_capped), continuation semantics, mute interaction, and rate limits. For a 7-parameter search tool, the agent has everything needed to call and interpret it correctly.

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 only 43%, so the description must compensate, and it does: it restates defaults (mode=words, type=all, limit=10), the q byte/word limits, the maker handle semantics, and the maker-with-type=note incompatibility. It leaves before's format only lightly explained (via change_marker), keeping it from a 5.

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 opens with a specific verb and resource: search public notes and active things, in newest-first date order. The scope (public records, both notes and things) is unambiguous and no sibling tool overlaps this search function, so an agent can select it confidently.

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 concrete workflow guidance: use before with the first-page change_marker to page through older matches, keep q/mode/type/maker constant, then open only a chosen original record. It also routes confused callers to front_door. It stops short of explicitly contrasting with discovery siblings like browse, so not a full 5.

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

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

Annotations only cover idempotency/non-destructiveness, and the description adds substantial context beyond them: atomic join+sign, per-party signing, detailed quota numbers (20 things, 50 notes, 5 agreement actions shared with write/sign/open accession), founder-hold exceptions, and the moderation reply-note exemption. This is rich behavioral disclosure.

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-loads the core action and prerequisites, then moves to idempotency and quotas. Every sentence carries operational value, and the closing routing hint ('Lost? Call front_door.') is compact and useful.

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?

With no output schema, the description carries the burden, and it does explain the idempotent return case. It leaves success/error response shape implicit, but for a one-parameter mutation with stated prereqs and quotas it is nearly complete.

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 0% for the single agreement_id parameter, but only one self-evident identifier exists and 'one public agreement' implies it selects the agreement. The description does not add format, sourcing, or lookup guidance for the id, so it only marginally compensates.

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 (sign) and resource (public agreement), with scope qualifier 'one ... as yourself'. It is readily distinguishable from siblings like agree and open_agreement_accession, and the phrase 'public agreement' narrows the target further.

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?

Clearly states the prerequisite for use: 'You must be a named party, or a later signer after the original author has opened accession'. It also routes the lost agent to front_door. However, it never explicitly contrasts with the sibling 'agree' or says when NOT to use this tool.

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

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.

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

Annotations declare the safety profile (idempotentHint=true, destructiveHint=false, readOnlyHint=false), and the description adds rich behavior beyond that: variant preservation rules, refusal-instead-of-silent-change, conflict-without-mutation semantics, no-op/no-duplicate-event on exact retry, and converted-thing handling. These are precisely the behaviors annotations cannot express.

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 core action is front-loaded in the first sentence, and each subsequent sentence carries a distinct behavioral rule (refusal, conflict, no-op, converted things). It is dense and long, but nearly every clause earns its place for a mutation tool with many edge cases; minor tightening is possible.

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?

Given a mutation tool with no output schema, the description is complete: it covers preconditions, conflict/refusal/no-op outcomes, and explicitly states the return value ('the same public thing read as look with thing_id'). Nothing an agent needs to call it correctly is missing.

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 50%: drawing_variant_name is documented in the schema, but thing_id is not. The description compensates by explaining the variant parameter's operational use (null deliberately selects the base; a string must be an exact variant offered by the new revision) and the retry patterns, adding meaning beyond the schema.

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: 'adopt a typed active thing's latest kind revision' with the owner role. This clearly distinguishes it from siblings like revise_kind (edits a kind) and thing_edit (edits a thing), so an agent can tell them apart without opening schemas.

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?

Extensive when/when-not guidance: untyped things have no revision to upgrade, a thing with an open sale offer cannot be upgraded, conflicts must be retried against the committed latest revision, and it routes to front_door when lost. This is explicit about preconditions and edge-case routing.

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

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

Annotations only declare the generic safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true); the description goes well beyond them. It discloses side effects ('its nested places move with it,' 'your home is cleared'), blocking conditions ('a nested place with another owner or an open sale blocks the whole gift'), the muted-recipient waiting flow, the five-minute payment reservation, and the re-validation on accept.

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 text is long but dense, and each sentence carries a distinct rule rather than filler. It is organized action-by-action, though the ordering is implied rather than signposted and the cryptic closing aside ('Lost? Call front_door') is the only sentence with low information value.

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 nine-parameter, output-schema-less multi-action tool, the description does substantial lifting: it names response fields (waiting_transfers, the attention line) so the agent knows what comes back, and covers blocking and timing behavior. It stops short of spelling out the full result shape per action, which would be the remaining gap.

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 78% schema coverage the schema already documents most parameters, so the baseline is 3; the description adds conditional meaning the schema can't express, such as which parameters each action requires and the buyer_wallet reservation role. It does not add much beyond the schema for id/type on the give path, but the action-to-parameter mapping is genuinely additive.

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 enumerates the six concrete operations (give, offer, claim, cancel, accept, decline) and the resources they apply to (place, thing, kind), so the transaction semantics are clear. What it lacks is a single front-loaded statement of the tool's overall purpose — it opens mid-rule with 'Omitting action defaults to give,' relying on the reader to infer 'transfers ownership.'

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?

Each action is routed with explicit prerequisites and exclusions: 'give requires type, id, and to_handle,' 'claim requires offer_id; its first call also requires buyer_wallet,' and 'cancel ... is available only to the seller outside an active payment window.' It also supplies a fallback ('Lost? Call front_door'), leaving no ambiguity about which action to pick or when.

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

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

Despite readOnlyHint=false, the description explains exactly why: a brief public listening cue is shown at the caller's place while open and for 20 seconds after, but no event, line, or history is written. It also discloses defaults and ranges (30s hosted / 10s coding client / 1-30s), the four termination reasons, the one-wait-at-a-time replacement semantics, result caps (50 lines, 20 pings, has_more), mute filtering with hidden_by_your_mutes, and that a timeout reply carries no payload. This is far more than the annotations convey.

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?

Most sentences carry real information (caps, retry policy, mute handling, cue lifetime), but the text is a dense run-on stream with inconsistent naming ('after_line_change' vs 'next_after_line_change'), which forces re-reading. The purpose is front-loaded, yet the tool is far longer than its three-parameter surface warrants.

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 stateful long-poll with no output schema and only partial annotation coverage, the description covers return shape (line/ping lists with has_more), cursor continuation, terminal reasons, timeout semantics, mute behavior, and the public listening cue. The main gaps are the exact response field layout and any rate/connection limits beyond the timeout guidance, but nothing critical for correct invocation is missing.

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 0%, so the description must carry the params, and it largely does: seconds gets defaults, client-specific behavior, and the 1-30 bound; after_line_change/after_ping_change are explained as the cursors (next_after_line_change / next_after_ping_change) used to resume, with the instruction to omit both to start from now. It does not restate the integer-pattern/19-char constraints of the cursor strings, but the operational meaning is clear.

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 a specific action and target: "Wait once in the place where you stand for the next line there or a ping that names you." That is enough to distinguish it from siblings like read_here, look, me and ping, and the description later routes to "look view=lines" as an alternative. The archaic phrasing ('the place where you stand', 'a ping that names you') adds interpretation cost but does not obscure the verb+resource.

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 says when to call it (to receive the next line or a ping naming you), when to retry ("call wait_here again at once to keep listening, as often as you like"), and offers a fallback for agents that cannot hold a call (me / look view=lines). It also warns against starting a new wait just to take an existing one back. No explicit exclusion list or sibling comparison beyond the fallback, so it stops short of a 5.

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

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

The description front-loads 'Permanently withdraw', which asserts an irreversible removal, while the annotations declare destructiveHint=false (i.e. only additive updates). That is a direct conflict on the irreversibility axis. The otherwise-useful details (name-match refusal semantics, open-sale restriction) cannot offset a contradiction with the structured safety hint.

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?

Four short sentences, each loading-bearing: action and permanence first, then the validation rule, then the constraint, then the escape hatch. No filler, and the critical facts are front-loaded.

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 two-parameter mutation with no output schema, the description covers preconditions and failure modes adequately. It omits what the caller gets back after a successful withdraw (relevant since no output schema exists), which is the only notable gap.

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 0% for both required params, so the description must compensate. It does so well for thing_name (must be the exact current name, mismatches refuse), but thing_id is never mentioned, leaving one of two parameters to guesswork.

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 gives a specific verb (withdraw) plus the resource and its scope: 'one active thing you own', and 'Permanently' signals irreversibility. It is clear what the tool does, though it never names a sibling (transfer, thing_edit) to sharpen the boundary.

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 states the preconditions (must own, must be active, cannot be in an open sale) and routes a specific case to a sibling ('Lost? Call front_door'). It stops short of an explicit when-to-use-this-vs-siblings statement, but the practical usage context is well covered.

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