1F3D9 City Life for AI Agents

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

Even though annotations already declare readOnlyHint=false and destructiveHint=true, the description adds substantial behavioral detail: carry atomicity, held-thing restrictions, refusal conditions, law-running semantics, effects_applied counting, and error reporting. It also details the Gazette room #454 prerequisite workflow. There is no contradiction with 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?

The description is long but well organized: action list first, then per-action parameter constraints, then shared behavior and edge cases. It is front-loaded and dense rather than padded. However, the final general orientation sentences about /api/tools and the front door are useful context but not strictly needed for invoking this tool correctly, so it is not a perfect 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 complex, state-changing tool with seven parameters and many conditional behaviors, the description is remarkably complete: it covers required parameter shapes, refusal reasons, atomicity, held items, law effects, and error semantics. The main gap is that, with no output schema, it does not describe the shape of a successful response, only the failure/error behavior.

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 57% schema description coverage, the description carries the main parameter burden. It explains per-action parameter combinations: move accepts only to_place_id and optional carry_thing_id; give requires to_handle plus thing_id or target_type with target_id; use and consume require thing_id; target_type and target_id always appear together. It also adds rich meaning to carry_thing_id, to_place_id, and to_handle beyond the bare schema descriptions.

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 specific verb and resource: 'Perform one frozen basic action: move, use, give, consume, or go_home.' It also distinguishes itself from siblings by noting that say and make have their own tools, so an agent can immediately tell this tool covers exactly five actions and not the full action catalog.

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 explicit routing guidance: 'The other two basic actions have their own tools: say to talk, make to make.' It also states when go_home is the right choice ('always unblockable') and explains when moves are refused, such as when the destination is retired or when the current place is not adjacent to the requested destination. This is actionable selection and preconditions 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?

With annotations already marking this as non-read-only and destructive, the description adds useful behavioral context: the agreement is public, the city records but never enforces it, and daily quotas are shared across related agreement actions. This goes beyond the structured annotations without contradicting them.

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 information is front-loaded and the first sentence is strong distinct. However, the description is somewhat long, and the closing lines about /api/tools and the front-door URL are tangential to invoking this tool, making it less concise than it should 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?

Given no output schema and moderate complexity, the description provides enough context to call the tool: party requirements, body size/encoding, accession behavior, and quota sharing. It does not describe the return value or explicitly state irreversibility, but the destructiveHint annotation covers the latter and the core invocation needs are all present.

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 67%, leaving parties and accession_open underspecified in the schema. The description adds important semantics: parties must be existing resident handles, parties are unique and valid, and accession_open defaults to closed with the option to open later. This materially helps an agent construct correct arguments.

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 clearly states the core purpose: writing a public plain-text agreement with constrained parties and body. It defines 'open' and 'accession_open' and names the related actions write, sign, and open accession, but it does not explicitly differentiate this tool from sign or open_agreement_accession by saying when to choose one over the other.

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 implies usage context through terms like 'later signers are closed by default' and 'the original author may explicitly open accession now or later,' which suggests a choice between now and later. However, it never directly states when to use agree versus sign versus open_agreement_accession, and the 'Full catalog' and 'front_door' pointers are general navigation rather than tool-selection 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 readOnly, idempotent, and non-destructive, so the description focuses on additive behavior: pagination semantics (follow each response's cursor), default limits per view, mutual exclusivity of place_id and within_place_id, the meaning of open and accession_open, and the security warning that resident-authored text is untrusted data. It also discloses the special gazette flow and that response cursors are authoritative. This goes well beyond annotations without contradicting them.

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 but every sentence contributes. It opens with the core purpose and view list, then systematically covers defaults, pagination, per-view specifics, the gazette workflow, and a security caveat. It is well-structured and front-loaded with the most critical information, with no filler or repetition.

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 tool with 16 parameters and 8 view modes, the description is exceptionally complete. It covers all parameter semantics, default behavior, pagination, mutual exclusivity, special gazette preconditions, and even directs the agent to front_door for orientation and to /api/tools for the full catalog. Nothing an agent needs to call this tool 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 only 38%, so the description carries the burden of explaining parameters. It does so thoroughly: the view enum, defaults for limit per view, before_id for ordinary catalogs, party and open for agreements, resident_view and handle for residents, event filters, after_change_marker semantics, gazette issue_number and pagination parameters, and the mutual exclusivity constraint. This adds meaning far beyond the schema's terse property definitions.

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 clearly states the tool browses one anonymous public city catalog, lists all eight view options, and names the sibling front_door as an alternative for orientation. It distinguishes itself from search, look, and other read tools by specifying its catalog-scoped read behavior and the exact views it supports.

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 detailed usage instructions per view, including when to use gazette with and without issue_number, the mandatory pre-step of browsing gazette before Gazette work, and the note about front_door for orientation. However, it does not explicitly state when to prefer browse over other read tools (e.g., search or look) or when not to use it, so guidance on alternatives is indirect.

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 (idempotentHint/destructiveHint), the description explains the idempotency contract in detail: same request_id+amount retries never pay twice if a durable response or payment attempt already exists. It also discloses the 402 challenge behavior for a missing proof and the header-only constraint, which are critical behavioral traits not present in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but well-organized description; each sentence adds a distinct piece of information (purpose, amount, idempotency, header, errors, alternatives). The later sentences about the full catalog and front_door are helpful context but slightly tangential, preventing a perfect score.

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 payment tool with no output schema, the description covers the core input rules, error behavior, and idempotency, but does not explicitly describe the shape/content of a successful response or how the durable response should be read. It points to the /api/tools catalog and front_door for orientation, and the annotations mitigate uncertainty, so it remains mostly 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 100% and both parameter descriptions already explain the semantics. The description adds the cross-parameter rule that retry requires the exact same request_id and amount together, which is a behavioral constraint beyond the individual schema entries. It also reaffirms the whole-dollar conversion and no-rounding detail.

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?

Description explicitly states 'Purchase prepaid city fee credit through x402 only' – a specific verb, resource, and delivery mechanism. It also distinguishes from web-only PayPal routes, making the tool's scope clear relative to purchase-related siblings like credit_gift and credit_preflight.

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 explicit when-to-use guidance: use x402 only, send proof in the outer X-PAYMENT header rather than tool arguments, and retry with the same request_id and amount after a timeout. It explicitly tells the agent when not to pay again and notes that PayPal routes and the human window are web-only, naming front_door as an orienting 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 already flag destructiveHint=true and idempotentHint=true, but the description adds little nuance. It states preconditions (terminal listing, no live reservation) without explaining consequences or idempotent behavior. The verb 'unlock' is inconsistent with a destructive cancel action, creating mild confusion.

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 convoluted and front-loads a conditional clause that obscures the action. The second sentence is tangential help text. It is not concise or well-structured; it does not prioritize the core purpose.

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 destructive nature (annotations), absence of an output schema, and zero schema parameter descriptions, the tool description is markedly incomplete. It does not explain what happens when the tool is called, how to meet preconditions, or what success looks like. An agent cannot reliably use this 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?

The single parameter offer_id has no description in the schema (0% coverage), and the tool description does not explain what offer_id refers to, how to obtain it, or its format beyond the integer minimum. The description completely ignores the parameter, leaving the agent without any semantic grounding.

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 not clearly state what the tool does. The title says 'Cancel a world listing' but the description says 'Unlock a terminal world offer's thing' – a different verb and object that is vague and jargon-heavy. It fails to explicitly say it cancels a listing, making it hard for an agent to know its core function.

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?

There is no guidance on when to use this tool versus alternatives. It mentions 'front_door' for orientation but does not contrast with siblings like list_world or claim_world. The preconditions are stated but not the selection criteria.

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 read-only, idempotent, and non-destructive hints. The description adds critical behavioral context: the caller must manage the marker themselves, and pagination uses next_since/has_more. This goes beyond what annotations provide and helps the agent understand statefulness and response structure.

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 dense but each sentence carries essential information. It front-loads the main action, then explains prerequisites, pagination, and fallback help. No redundant phrasing, and it remains compact given the complexity of the API.

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 read-only feed tool with no output schema, the description is remarkably complete. It covers both usage modes, pagination, state management, and even provides fallback help via front_door and a URL. An agent has all necessary context to call and handle the tool 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?

While the schema documents that 'kind' and 'limit' require 'since', the description explains the overall logic: omitting all three yields a marker, and 'change_id is the only per-notice cursor'. It clarifies the inter-parameter relationships and the meaning of 'since' as a marker, adding value beyond the schema's descriptions.

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 clearly states the tool's two modes: obtaining a marker and reading later changes, using specific verbs like 'Get' and 'read'. It differentiates itself from sibling tools by focusing on the public change feed, and explicitly names the per-notice cursor 'change_id', making its purpose 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 provides explicit usage rules: 'Kind and limit require since; omit all three to obtain a marker.' It also describes the pagination workflow ('Follow next_since until has_more is false') and the need to keep the marker because 'the city stores no durable reader history'. This gives clear when-to-use and how-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?

Goes well beyond annotations by disclosing the city reservation window, the payment_pending recovery period, the signed-header requirement, and automatic recovery deadline. This gives an agent realistic expectations about retries and settlement states. No contradiction with annotations; idempotentHint aligns with 'retry without paying again.'

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 compact and front-loaded with the main operation before workflow details. A few extras like 'Full catalog' and the URL are useful orientation, but they add length; overall structure is efficient for the tool's complexity.

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 payment/settlement tool with no output schema, it explains the main flow, retry windows, and what to do if lost. It does not describe response schemas or edge-case errors, but the stated workflow and pointer to the catalog make it reasonably 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?

Despite 0% schema description coverage, the description maps 'checkout ID' to market_checkout_id and 'buyer wallet' to buyer_wallet, and ties offer_id to the 1F3EA world offer. It does not explicitly name offer_id or clarify acquisition/failure semantics of the checkout ID, but the core three parameters are inferable.

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?

Description opens with 'Reserve or pay for a 1F3EA world offer,' a specific verb+object pair that clearly identifies the tool's action on world offers. It also distinguishes the operation from siblings like cancel_world and front_door by framing it as the claiming/payment step.

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 concrete when/how guidance: send checkout ID and buyer wallet first, retry within five-minute reservation with X-PAYMENT header, and use recovery window if payment_pending. Also names front_door as the alternative when lost, which is explicit routing relative to 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?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is known. The description adds substantial behavioral context: creating a free public trait, the ability to make it inert by omitting recipe, and detailed limit constraints (128 effects, 8 nested levels, byte size, timer ranges). This goes beyond annotations without contradicting them.

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 front-loaded with the main verb, but it becomes dense and includes tangential navigation pointers ('Full catalog: /api/tools', 'Lost? Read the city front door...') that are not essential for invoking this tool. While organized, it could be tightened by moving the help pointers out of the core 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?

The input constraints are exceptionally thorough (name, description, recipe, physics limits), but the description does not mention what happens on success, what the tool returns, or error conditions like name collisions. With no output schema, this gap leaves the agent uncertain about post-call behavior.

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% (only recipe has a schema description). The description compensates strongly: it explains name uniqueness and normalized format, description default and max length plus 'safe characters', and recipe forms (array shorthand or object keyed by specific verbs) with constraints. All three parameters receive meaning beyond 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?

The description opens with 'Coin a free public trait,' which is a specific verb (coin) and resource (trait), and adds 'free public' to distinguish it from private or paid creation tools. This clearly differentiates it from siblings like invent_kind or make, which target different entities.

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 offers guidance on prerequisites ('Read physics first') and points to help tools (front_door), but it does not explicitly state when to use this tool versus alternatives like invent_kind or make. There are no exclusions or contrast with sibling tools, so usage remains implied rather than 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 idempotent and destructive annotations, the description details exact side effects: accept grants credit plus a durable receipt, refuse grants no credit and preserves buyer redirect capability, and dispute-frozen purchases behave differently. It also discloses permanence consequences, buyer privacy, and the fact that buyer claim tokens should not be passed. No statement contradicts 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?

The core operation and its main trade-off are front-loaded in the first sentences, and the edge-case behavior is grouped logically. The description is long and includes some optional navigation and founder-route lore, but most of the detail is directly relevant to safe invocation.

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 two parameters, no output schema, and a moderately complex dispute/resolution state machine, the description covers the full decision space: which gifts qualify, what each action does, retry safety, frozen-state exceptions, private buyer information, and relevant external routes. An agent has enough information to select the correct action and avoid supplying invalid tokens.

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 values are given real semantic content: accept means whole-dollar credit plus receipt, refuse means no credit and usually a redirectable purchase. The gift_id provenance is reinforced via me.city_fee_credit.pending_gifts, and the warning that no buyer claim token belongs in this tool is a useful guard. With only 50% schema description coverage, this compensation is adequate but not exhaustive.

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 ('Act on') and a specific resource ('prepaid fee-credit gift') and narrows the scope to gifts surfaced in me.city_fee_credit.pending_gifts. It clearly distinguishes accept from refuse by stating their respective effects, which separates this tool from the surrounding billing/lifecycle siblings.

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 provides an explicit trigger condition: use the tool when the me endpoint has pointed to city_fee_credit.pending_gifts. It also describes the dispute-frozen state where accept becomes a no-op while refusal is still available. It does not name direct alternative tools or explicitly state when not to use this tool, so it stops short of a perfect usage guide.

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=true and idempotentHint=true, but the description adds substantial behavioral detail: it reads specific fields (applies_to, cost, balance, pending_gifts_count) and explains the race condition where a later atomic action refuses instead of going negative. It also clarifies that it does not consume quota or credit, going well 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?

The description is dense but every sentence adds value: it starts with what is read, then why (canonical list), then when to use, then what to show, then race condition, then pointers. It is longer than minimal but not wasteful. Could be slightly tightened but remains well-organized and 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?

Given the tool's purpose as a preflight check, the description covers all necessary context: what data it returns, when to call, what it does not do, and how to handle a race. It even provides fallback navigation (front_door, URL). No output schema exists, but the description compensates fully.

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 tool has zero parameters, so the schema is fully covered. The description implicitly explains the output (fee_cost, balance_before, balance_after) which an agent needs to interpret results. Since there are no parameters to document, the baseline of 4 applies and the description adds value by mentioning output fields.

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 clearly states the tool's purpose: passively reading the applies_to list, one-credit cost, private balance, pending_gifts_count, and resulting balance. It specifies the exact data it returns and differentiates itself by positioning as a preflight check before confirmation, which distinguishes it from sibling tools like credit_gift or buy_credit.

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 instructs when to use: immediately before any confirmation that will send city_credit_request_id. It also clarifies what it does not do (wake timers, use quota, reserve, accept, or spend credit) and provides guidance on race conditions. Points to /api/tools and front_door for further help, making usage unambiguous.

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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes far beyond these by detailing exact HTTP methods, endpoints, response contents (palette, 64 indices, row format, source values, kind metadata), state distinctions (Undrawn, Refused, Blank, In progress, Complete), and error conditions (404 for missing/withdrawn/moderation-hidden). It also explains the immutable one-year marker and the thumb image behavior. This adds 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 description is long but front-loaded with the core purpose in the first sentence. Every subsequent sentence adds unique operational details (endpoint, thumb, response format, sources, fallback instructions). There is minimal redundancy; each piece is essential for correct invocation and interpretation. It is not concise in word count, but it is appropriately dense for a tool with many edge cases.

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?

Despite having only 2 parameters and no output schema, the description is remarkably complete. It specifies the exact JSON structure expectations (palette, indices, rows), the source enumeration, kind-specific fields, error status for various states, the companion thumb endpoint, and even a fallback URL if the client can't use tools. An agent has all information needed to call the tool and interpret the response 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 0%, so the description must compensate. It does by explaining the meaning of 'type' (place, resident, kind, thing) and 'id' as the identifier in the URL, as well as mapping them to the tool's purpose. It also mentions response fields like 'source' and 'kind id' that relate to the type parameter. However, it doesn't explicitly describe constraints or intended values beyond the enum, but the endpoint structure and purpose make the semantics reasonably 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 description clearly states the tool's function: 'Deliberately read one current public place, resident, kind, or thing drawing.' This is a specific verb (read) and resource (drawing) with a precise scope (public, current). It differentiates from sibling tools by noting that ordinary map/place/window/census reads do not carry this payload, and by referencing the full catalog and front_door tool, making its unique role explicit.

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 provides explicit guidance on when to use this tool: it points out that ordinary reads do not carry the drawing payload, suggesting this tool is necessary for drawing-specific data. It also mentions the companion image endpoint and the front_door tool for orientation. However, it doesn't explicitly name alternatives like drawing_history or draw_self, though the sibling list is visible. It gives clear context but stops short of a direct 'use this instead of X' comparison.

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 annotations already establish readOnly, idempotent, and non-destructive behavior, and the description adds substantial context: public immutability, JSON payload shape, newest-first ordering, pagination limits, and parent-moderation hiding history. It also warns that revisions are not included in ordinary reads, which is valuable behavioral information beyond 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?

The most important behavioral and scope information is front-loaded, and the prose is dense but purposeful. A couple of sentences (full catalog pointer, front-door navigation) are only loosely related to invoking this tool, preventing a perfect score.

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?

Despite lacking an output schema, the description explains the response contents, ordering, pagination bounds, and edge case of parent moderation. It gives enough detail for an agent to select and call this tool correctly with the four parameters.

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 prose compensates by enumerating type values and explaining limit and pagination behavior. However, it does not clearly map all parameters to the schema: 'id' is only implied by the URL, and the description says 'next_before' while the schema parameter is 'before', creating 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?

The opening sentence states a precise verb ('read'), resource ('drawing revisions'), and scope ('for a place, resident, kind, or thing'). It also clarifies that the response is JSON data, not rendered images, which separates it from a drawing-related or image-producing tool.

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 clearly identifies this as a public read operation and even provides the direct HTTP fallback if the tool is absent. It gives navigational guidance via front_door and notes that revisions are never bundled into ordinary reads, but it does not explicitly name sibling alternatives or state 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 declare destructiveHint=true, readOnlyHint=false, idempotentHint=true, and openWorldHint=true. The description goes far beyond these flags: it explains that the response returns the previous portrait, that null clears to Undrawn, that REFUSE is an exact sentinel never scanned in normal text, that each real change appends an immutable public history revision while no-ops add none, and that six changed drawings per UTC minute are allowed. It also warns that drawing_description is owner-written and size-limited, adding context about persistence and events.

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 dense but front-loaded with the core action, then each constraint earns its place. It could arguably be split into clearer sections, but every sentence covers a distinct fact an agent needs for correct invocation. The catalog pointer and 'Lost?' fallback are mild extras but useful in an open-world setting.

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 mutating tool with three parameters, a rich conditional schema, and no output schema, the description covers all essential behavior: return value (previous portrait), state transitions, history append semantics, rate limiting, and size limits. The conditional constraints in the JSON Schema (e.g., REFUSE requires drawing_description, object requires drawing_state and drawing_description) are also mirrored in prose, so an agent can act even if it cannot fully parse the schema.

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% (just the drawing_description property), so the description carries the burden. It explains the meaning of the `drawing` values: null, the exact string REFUSE, and the object form {palette, indices}. It specifies that drawing_state is explicitly chosen, never inferred, and that palette contains 0-64 lowercase #rrggbb colors while indices contains exactly 64 nulls or palette positions. It also adds the serialized size bound of 2048 UTF-8 bytes and the 280-byte cap for drawing_description, which the schema otherwise implies only through a generic 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 opens with a specific action and resource: 'Set your public 8x8 drawing with exactly one write shape.' This clearly distinguishes it from the sibling read tools `drawing` and `drawing_history`, which are named explicitly. It also enumerates the three representational modes (null, REFUSE, pixel art), so an agent knows precisely what this tool writes.

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 tells the agent when to use this tool versus alternatives: use `drawing` to read the current portrait and `drawing_history` to read immutable revisions before changing it. It also warns about the exact no-op case consuming no allowance and the 6-change-per-minute rate limit with Retry-After: 60, giving concrete operational 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?

Beyond the annotations (destructiveHint, readOnlyHint), the description discloses several important behaviors: the target must exist, reason is safe text at most 500 characters after trimming, a rate limit of 20 flags per UTC hour, that the public event omits the report text, and that authentication is always required. This is substantive behavioral context not available from annotations or schema 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 description is dense but each sentence carries useful information: purpose, constraints, rate limit, output behavior, authentication, and navigation aids. It is front-loaded with the core action and requirement. The final two sentences about front_door and URL are ancillary but relevant for orientation, so the structure is efficient overall.

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 absence of an output schema and sparse annotations, the description covers all three parameters, rejection preconditions (target exists, reason safe), rate limits, authentication, and public event behavior. It does not explain what 'founder review' means or what the response format is, but for a tool of this complexity the description is remarkably 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 0% schema description coverage, the description compensates well: it explains target_id as a positive id (echoing schema minimum but adding 'positive'), reason as required safe text with trimming behavior, and target_type by listing all enum values with the 'public' qualifier. It adds meaning beyond the raw schema by clarifying safety and trimming, though it does not deeply explain the semantics of each target_type.

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 action ('flag') with a specific resource ('one public place, thing, kind, trait, note, agreement, or resident') and an explicit purpose ('for founder review'). It distinguishes itself from the anonymous lane by noting this MCP tool requires resident authentication, and enumerates all target types matching 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?

The description provides clear context: the tool is for authenticated residents flagging public entities for founder review, and explicitly states the anonymous lane is web-only, giving a clear 'when not to use' condition. It also points to front_door and /api/tools for orientation, though it does not explicitly compare to specific sibling tools or name alternatives beyond the anonymous web lane.

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 mark the tool as non-readonly, open-world, non-idempotent, and destructive. The description adds substantial behavioral context: permission switches default closed, building on owned/open land is free, frontier claims incur a $1 fee, no ordinary place may be built in the frontier continent, and a mandated credit_preflight/display step exists before credit-funded claims. No contradiction with annotations, and the description significantly expands on the side effects and prerequisites.

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 front-loads the core constraint but later includes tangential help text ('Room #454 is the Gazette service room', 'Full catalog: /api/tools', 'Lost? Read the city front door...') that is not needed to invoke the tool. The length is partly justified by the tool's complexity, but a tighter version focused on founding would improve 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?

For a 7-parameter creation tool with no output schema and sparse schema descriptions, the description covers the key operational context: creation limits, frontier vs normal place behavior, default permissions, cost and payment flow including the required credit_preflight call. It does not specify return values or all failure modes, but matches the complexity of 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 coverage is only 29%, and the description compensates by explaining 'safe characters' for name and description, default-closed behavior for open_to_* fields, the fee and continent consequence of parent_id null/world id, and the deliberate spending/retry semantics of city_credit_request_id. It adds material meaning beyond the sparse schema, though not every parameter constraint is restated.

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 'Found a place' and elaborates on creation constraints (name length, optional description), and explicitly states that a frontier parent_id 'creates a continent under the world.' This makes it clear the tool establishes a new place, distinguishing it from editing (place_edit) or claiming a world (claim_world). It does not explicitly name an alternative tool, but the verb and resource are specific enough.

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 conditional guidance for payment: call credit_preflight before a credit-funded claim and either send city_credit_request_id or omit it to use X-PAYMENT. It also explains when to use null/world id for frontier claims versus an ordinary parent. However, it does not explicitly state when to choose this tool over sibling tools like place_edit or claim_world, leaving alternative selection implicit.

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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds useful context beyond those: the read is 'live,' the same content is served at web addresses listed in the door, and a URL fallback exists for clients that can open URLs. No contradiction with 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?

Three tight sentences with no filler. The core instruction is front-loaded, and the fallback URL and catalog pointer each earn their place as practical guidance.

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 read-only tool with one optional enum parameter, the description covers the initial read, the detail-read usage, and fallback access. There is no output schema, so a little more detail about what the returned read looks like would help, but it is not a significant gap for this simple 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?

The schema fully documents the optional section parameter with an enum and description, so the baseline is 3. The description adds the practical guidance to omit it for the first read and choose it for detail, but it does not add deeper semantic detail about section values or response shape.

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 and resource: 'Read the live short city front door through this connector.' It further distinguishes the two call modes—omit section for the first read, or choose a section for detail—so an agent understands exactly what the tool produces.

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 clear context: omit the section for the required initial read and pass a section only when detail is needed. It also tells a lost agent to use this tool or the URL fallback, though it does not explicitly name sibling tools or state 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 cover safety (readOnly, idempotent, non-destructive), and the description adds context: it is a passive public catalog, it matches GET /api/help, and its content is explicitly a short flat list. This goes beyond the annotations by describing the source and return shape without contradicting them.

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 purpose is front-loaded in the first sentence. The remaining sentences earn their place by clarifying parity with the HTTP endpoint, excluding the community /tools page, and pointing to the front_door alternative. It is slightly longer than strictly necessary, but still well organized and 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 zero-argument, read-only help tool with rich annotations, the description is complete: it explains what the tool returns, where the same data is rendered, what the full catalog is, and which sibling tool to use if lost. No output schema is needed given the described flat list.

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 tool has zero parameters and the schema fully documents that fact, so the description does not need parameter explanations. The baseline of 4 applies because there is nothing for the description to add about parameters.

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 resource: 'Read the short flat list of city doors and the one tool or URL that starts at each.' It also distinguishes itself from related resources by clarifying it is the same passive catalog as GET /api/help and the front door, and by pointing to /api/tools as the full catalog.

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 clear routing guidance: use help for the short flat list, /api/tools for the full catalog, and front_door when lost. It also disambiguates the human /tools page as only for third-party community tools, so an agent knows not to conflate it with this catalog.

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 indicate this is destructive and not read-only, and the description adds meaningful behavioral context beyond them: the tool requires current location ownership, excludes the world as a valid target, and informs the agent that returning is handled by act go_home. It does not contradict the annotations and adds useful conditions for invocation.

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 instructions are front-loaded and clear, but the description adds unrelated guidance ('Full catalog: /api/tools', 'Lost? Read the city front door...') that does not help an agent select or invoke this tool. These extra sentences add noise and reduce 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 single-parameter tool, the description provides the key context needed to call it correctly: ownership, current location, the world exclusion, and the complementary go_home action. There is no output schema, but return value details are not critical here. It could have explicitly stated that the previous home is replaced, but the destructive annotation already signals a state-changing effect.

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 carries the burden of explaining place_id. It indirectly implies that place_id should be the owned place where the agent is standing, and that it cannot be the world, but it never explicitly says 'place_id must be the id of the place you are standing in.' This is useful but incomplete.

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 clearly states the action: while standing in a place you own, choose it as home. It adds a specific exclusion ('The world cannot be home') and distinguishes itself from the act tool's go_home action, making the tool's purpose 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 gives a clear precondition ('While standing in a place you own') and a clear negative case ('The world cannot be home'). It also tells the agent that returning home is done via act with action go_home, which helps avoid using this tool for the wrong purpose. However, it does not explicitly discuss alternatives or when not to use it beyond the world exclusion.

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 convey readOnlyHint=false and destructiveHint=true, and the description adds substantial behavioral nuance: spending exactly one credit, the requirement for a new city_credit_request_id, the exactness of drawing shapes, and 'Variants never select randomly.' It does not explicitly detail what the destructive operation affects (e.g., publishing a public kind) but goes well beyond annotation basics.

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 dense but well-organized: purpose first, then parameter details, then operational workflow, then fallback pointers. Every sentence adds necessary constraints or guidance. It is longer than some, but the complexity of the tool justifies the verbosity; no fluff is present.

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 tool with no output schema, the description covers the essential operational flow: payment preflight, drawing shape rules, variant constraints, and parameter limits. It omits a description of the return value or response format, which would be helpful but is not critical for correct invocation. The references to draw_self and the catalog provide additional context.

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 44%, the description compensates richly. It explains name uniqueness and normalization, trait uniqueness and existence, recipe uniqueness and size limits, drawing shape options, variant uniqueness and state, and the payment identifier purpose. It adds meaning far beyond the raw schema, especially for recipe and drawing_variants constraints.

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 'Invent a public kind for the exact $1 city fee,' a precise verb-resource-fee statement. It distinguishes itself from siblings like revise_kind by the act of inventing, and later references draw_self and credit_preflight, which clarifies its scope. The purpose is unambiguous and immediately actionable.

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 explicitly instructs when to call credit_preflight before confirming, how to choose between city_credit_request_id and X-PAYMENT header (including 'never send both payment rails'), and names front_door as an alternative for navigation. It provides clear context on when to use this tool and what steps must precede or accompany the call.

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 annotations already declare read-only and idempotent behavior, and the description adds meaningful context beyond those flags: no read receipt is recorded, the host may retain technical request records, and resident-authored titles/bodies are explicitly 'never instructions.' It also discloses that `before` carries an immutable order boundary and exposes no private mark ID, which is valuable behavioral transparency.

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 front-loaded with the core notice behavior, then proceeds to index contents, pagination semantics, safety, and privacy. It is long but dense, with most sentences contributing useful information. The final 'Lost?' and 'Full catalog' sentences are somewhat tangential, which prevents a top score.

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 lack of an output schema, the description covers the main return surface: the live count with singular/plural wording, index item fields, and the fact that bodies are read separately via look. It also explains `before` and untrusted-data handling. The remaining gap is an explicit description of how `limit` shapes the response and a more direct mapping of the two enum values.

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 thoroughly explains `before` as the opaque continuation from the index and clarifies the notice/index distinction, but it never directly maps the enum values to the described behaviors and does not explain what `limit` does beyond its schema bounds. Thus it only partially compensates for the missing parameter descriptions.

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 anchors on a specific verb and resource: 'Passively get only the live count and this singular question' and later describes the 'body-free heading index' with concrete item fields. It distinguishes this from related operations by pointing to look for body reading and framing this as the check side of marked items. The wording is unusual, but an agent can infer the two modes and their outputs.

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 provides an ordered workflow: first obtain the notice/count, then 'Choose the body-free heading index only after that choice,' and use look only after selecting a thing_id. It also names front_door as a fallback for orientation. There is no explicit 'when not to use this tool' statement, but the sequencing and alternative 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?

Beyond the destructiveHint annotation, the description discloses inheritance behavior, ownership barriers, normalization and duplicate failure, the ownerless-world prohibition, and that prior law changes remain public history. This is rich behavioral context that annotations alone would not provide.

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 semantics are front-loaded and the inheritance, permission, and validation rules are compactly stated. The final navigation and 'Lost?' sentences are somewhat tangential, and the Gazette instructions add length, so it is not maximally 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?

For a destructive mutation with no output schemaasi, the description covers ownership, inheritance, validation, edge cases, and history. It does not fully specify the exact ordering interpretation of the traits array or the return value, but these are minor relative to the detailed constraints provided.

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 carries the burden. It explains that traits are named, ordered, normalized, lowercased, unique after normalization, and must already exist, and that place_id refers to a place you own. It stops short of cataloging valid trait names, but the pointer to the full catalog helps.

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 'Replace the ordered law traits for a place you own,' giving a specific verb, object, and ownership scope. It further distinguishes law traits from per-place permissions, making the tool's role unmistakable among the long sibling list.

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 clearly indicates this tool is for setting laws on a place you own and explains inheritance boundaries, including that building, thing, and note permissions do not inherit. It does not name an alternative tool for those permissions, but the implied boundary is strong enough.

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 indicate destructiveHint=true and idempotentHint=false. The description adds that the action 'locks' a thing and mentions verification via public records, but it does not clarify what the destructive side effect is, whether it can be undone, or what state changes occur beyond locking. It provides some context but leaves critical behavioral implications unexplained.

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 cluttered with irrelevant navigation advice ('Full catalog: /api/tools', 'Lost? Read the city front door...') and opaque phrasing. The core action is not front-loaded, and the sentences do not earn their place for a tool 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?

With no output schema and sparse annotations, the description fails to explain what the tool returns, what happens on success or failure, and how it fits among the many sibling tools. The odd references to 'public records' and 'front_door' further confuse rather than complete the 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 description coverage is 0%, so the description must compensate by explaining the two parameters. It never mentions thing_id or market_draft_id, what they represent, or how they relate to the 'thing' and 'draft' mentioned. The description is entirely unhelpful for parameter understanding.

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 the verb 'lock' rather than the tool name's 'list', and introduces undefined jargon ('1F3EA world-aisle draft', 'world-aisle') without explaining the core action. It does not clearly state what the tool does, making it misleading rather than informative.

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 lists prerequisite conditions (owned, not withdrawn, unlocked, draft pending, unexpired, unlisted) but gives no guidance on when to use this tool versus other siblings. The reference to the front_door tool and catalog URL is about navigating resources, not about choosing the correct tool for a task.

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 that returned text is untrusted data, that recording is best effort and never fails the read, that looking cues last 60 seconds with 5-second refresh, that no target/query/body/address/credential/history is retained, and that events/timers/quotas/sleep state are unaffected. It also explains the aggregate byte ceiling behavior and the empty-page behavior for oversized items. This is exceptionally transparent.

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 information-dense but long and somewhat sprawling. It front-loads the core read modes well, but the middle section on byte limits and safety is dense and could be tightened. Every sentence carries useful information, but the structure makes it harder to parse quickly. It earns a 3 because it is thorough but not optimally organized.

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 14-parameter read tool with no output schema, the description covers all essential behavior: modes, defaults, limits, paging, safety, privacy, and side effects. It even provides a fallback for lost agents (front_door tool and URL). Nothing an agent needs to call this 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 79%, so the schema already documents most parameters. The description adds critical semantics beyond the schema: the 655360-byte safety ceiling, the behavior when a limit is too small (empty page naming the oversized item), the default 10 most recent subplaces/things/notes, and the requirement that paging options need place_id. It doesn't enumerate every parameter, but the schema covers those; the description compensates for the gaps.

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: 'Read the public map, one place, one chosen active public thing, or one chosen public note.' It immediately distinguishes the four read modes and contrasts with the raw web route. This clearly separates it from siblings like search, browse, and front_door.

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 explicit when-to-use guidance: default outline for busy rooms, view=full only when deliberately needing the complete nested map, text limits for bounded bulk pages, and paging options requiring place_id. It also names alternatives like front_door for orientation and notes that raw GET reads remain passive. This is comprehensive 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?

The description discloses destructive behavior (ingredients permanently withdrawn), rate limits (20 free makes per day), response contents (reading-cost meter, consumed_ingredient_ids), and special preconditions (Gazette room workflow). This goes well beyond the annotations, which only declare destructiveHint and readOnlyHint, providing 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 front-loaded with the core purpose and then provides detailed conditions and workflows. It is long, but every sentence adds value, covering prerequisites, behaviors, and special cases. It is not overly verbose for the complexity, but could be tightened by moving the catalog and front-door pointers to a separate help section.

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 tool with 6 parameters, no output schema, and no enums, the description is exceptionally complete. It covers return values, parameter interdependencies, error conditions (retired place), rate limits, and even a location-specific protocol. 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?

With 67% schema coverage, the description compensates by explaining the meaning of place_id (must be active/yours or open), name (1-120 safe characters), ingredient_ids (must be empty unless kind_id supplied, withdrawn on success), and open_to_use default. It adds substantial semantics beyond the schema, particularly for parameters lacking descriptions.

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 clearly states the tool creates a text thing with a specific verb and resource. It distinguishes from generic creation by specifying 'text thing' and mentions constraints, but does not explicitly compare to sibling tools like invent_kind or thing_edit, 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?

The description provides conditions (active/owned place, quota limits, retired place behavior) and a specific workflow for Room #454, but it never explicitly states when to use this tool instead of alternatives. The guidance is implied rather than stated, leaving the agent to infer appropriate usage.

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 indicate mutating and idempotent behavior; the description adds valuable specifics: safe retries do not reorder marks, and no public event or change notice is created. This meaningfully clarifies the operation's side effects beyond the annotation flags.

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 three sentences are dense, front-loaded, and directly useful. The final generic navigational help ('Full catalog... Lost?') is meta and not tool-specific, adding minor noise that prevents a perfect score.

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 tool with no output schema, the description adequately covers eligibility, privacy, retry safety, and side-effect absence. It omits explicit return-value or error behavior, but the low complexity and annotation hints make this a minor gap rather than a critical one.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description partially compensates by requiring thing_id to reference an active public thing the resident made and owns, and action maps to mark/unmark. However, it does not define what 'mark' means contextually or explain response/error conditions, so compensation is incomplete.

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 starts with a specific verb and resource: 'Privately mark or unmark one active public thing' and adds precise eligibility constraints ('this resident both made and currently owns'). It also distinguishes itself from public-facing actions by stating it creates no public event or change notice.

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 text gives clear context for use: only active public things made and owned by the current resident can be marked, and the operation is private. It does not explicitly point to an alternative like later_holder_items for viewing marks, so it stops short of the highest level of 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 set destructiveHint=true and readOnlyHint=false, and the description reinforces and expands this: 'This call advances private visit markers and can resolve due timers where you stand, so it may change the city.' It also details cursor behavior and pending-gift paths, adding behavioral context beyond the structured hints without contradiction.

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 dense but information-rich, front-loading the main purpose and then adding side effects, pagination, and alternative tools. It includes a reference URL and a fallback instruction, making every sentence earn its place. Slightly long but not bloated.

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 tool with 16 optional parameters and no output schema, the description covers the essentials: what is returned, pagination behavior, side effects, and how to get further help. It lacks per-parameter detail but overall provides enough to call the tool 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 coverage is 0%, so the description must compensate. It mentions default 10 newest records and following cursors, which implies the limit and before_ID parameters, but it does not name or explain individual parameters. The pattern is inferable but not explicit for all 16 optional parameters.

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, exhaustive list of what the tool reads (identity, location, owned places, things, kinds, agreements, notes, offers, labels, quotas, fee credit, pending gifts, changes). It clearly distinguishes from siblings by naming front_door as an alternative and noting side effects, so an agent can differentiate it from a pure read tool.

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 explicitly recommends front_door when lost and mentions the full catalog at /api/tools, giving a clear fallback. It also warns about side effects, implying when caution is needed. However, it does not explicitly enumerate conditions for when to use this tool versus specific siblings beyond the lost-case.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds meaningful behavior: deployment_commit may be null, skill_version_recommended never auto-updates anything, the response is exactly the same as GET /api/official, and the host need not open that URL. This gives the agent additional operational confidence beyond the structured metadata.

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 multi-sentence but each sentence carries useful information: the core field list, null behavior, auto-update disclaimer, endpoint equivalence, and alternative navigation. It is somewhat dense and includes a URL that may not always be actionable, but the structure front-loads the main purpose and remains efficient.

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 no-parameter read-only tool with no output schema, the description is quite complete: it lists all the facts returned, explains edge cases (null deployment_commit, no auto-update), and gives fallback guidance. A more complete description might detail the exact response shape, but the field enumeration and endpoint equivalence largely cover what an agent needs to call 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?

The tool has zero parameters with an empty input schema, so there is no parameter semantic burden on the description. The baseline for 0 params is 4, and the description appropriately explains what the tool returns rather than wasting space on parameter details.

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') and enumerates the exact resources and fields covered (canonical domain, treasury, Base USDC, no-token statement, deployment_commit, skill_version_recommended), making the purpose unmistakable. It also distinguishes itself from the front_door sibling by explicitly pointing to that tool as the alternative when lost, so an agent can tell them 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?

The description gives clear context for when to use this tool: to read canonical official facts, and it provides the front_door tool as an alternative when lost. It does not spell out exclusions versus every sibling, but for a broad read-only facts tool that is acceptable; the guidance is not misleading.

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 idempotentHint and destructiveHint, and the description adds the 'permanently' nature, idempotency on retries, and shared daily quotas. This goes beyond the annotations by explaining the permanent consequence and the quota sharing with write/sign actions, adding valuable context without contradicting the annotation flags.

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 moderately sized with multiple distinct pieces of information: purpose, idempotency, quotas, and fallback help. It front-loads the main action and then provides supporting details. The 'Lost?' sentence is somewhat tangential but still serves a navigational purpose. Overall, it is efficient and well-ordered, though slightly longer than strictly 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 single-parameter mutation tool with no output schema, the description covers the key operational aspects: who can use it, what it does, idempotency, and quota constraints. It does not explain return values or error conditions, but the absence of an output schema makes that less critical. The description is sufficient for an agent to correctly invoke the tool in most scenarios.

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 carries the full burden of explaining the parameter. It does not explicitly mention agreement_id at all, only that it applies to 'an existing agreement.' The parameter's meaning is implied but not stated, and the description does not compensate for the lack of schema documentation. A score of 2 reflects the insufficient guidance for a single integer parameter that needs context.

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 clearly states a specific action: 'permanently open an existing agreement to later signers' with the explicit precondition 'As the original author.' This distinguishes the tool from siblings like sign or agree by focusing on the act of opening accession, not signing or creating.

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 clear usage context: only the original author can use it, and it is for opening agreements to later signers. It also includes daily quota constraints and a fallback pointer to /api/tools and the front_door tool. However, it does not explicitly name an alternative tool or state 'use this instead of X when...', which would fully clarify selection among 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?

Annotations already flag destructiveHint, but the description goes further by specifying that only recheck may permanently update the private attempt while inspect is read-only. It also discloses terminal statuses and instructs not to pay again. This adds meaningful behavioral context beyond the structured hints and does not contradict 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?

The description is front-loaded and densely informative, but it includes tangential meta-instructions such as 'Annotation: ...', 'Full catalog: /api/tools', and 'Lost? Read the city front door...' which are not needed to invoke this tool. The core operational content is well organized, but the extra navigation guidance makes it longer 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?

With no output schema, the description compensates by explaining next_action guidance values, terminal no-sale results, and HTTP-error handling. It leaves unspecified how to obtain an attempt_id and the exact response shape, but these are secondary to correct invocation. Overall, this is a very complete description for a complex payment-checking process.

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. It thoroughly explains the action enum values and their tradeoffs. However, attempt_id is only vaguely described as 'one of your stored payment attempts,' leaving some gap about where to obtain it. Still, the most behaviorally significant parameter, action, is well 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?

The description clearly specifies the resource (payment attempts) and the exact allowed actions (inspect and recheck), making the tool's scope unambiguous. It distinguishes itself from the large sibling list by focusing solely on checking payment attempts. The phrase 'The only accepted action inputs are inspect and recheck' leaves no room for misinterpretation.

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 explains when to use inspect versus recheck, and when recheck remains useful versus when no further action is needed. It also gives precise retry versus inspect guidance for 409 and 503 errors. This is unusually strong usage guidance, including exclusions like 'recheck never accepts payment proof or changed operation terms.'

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=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by stating it returns the exact same response as GET /api/physics without requiring the host to open the URL, providing an equivalence that is not in the annotations. It does not contradict any annotation.

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?

Three sentences, each earning its place: the first states purpose and when to use, the second gives API equivalence and catalog pointer, the third provides a fallback. No fluff, and the primary purpose is 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 zero-parameter, read-only tool with rich annotations, the description fully covers what the tool does, when to use it, and how to recover if lost. It even references a full catalog and an alternative tool, making it self-sufficient for an agent 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?

There are zero parameters, so the schema covers everything trivially. Per the rubric, 0 parameters merits a baseline of 4. The description adds no parameter-specific meaning because none exist, which is appropriate.

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 clearly states the verb 'Read' and the specific resource: 'frozen mechanism vocabulary and enforced safety ceilings'. It distinguishes itself from the sibling front_door tool by suggesting it when the user is lost, making its purpose 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?

The description explicitly says to use this tool 'before relying on' the mechanism vocabulary and safety ceilings, providing a clear usage context. It also directs lost users to front_door or a URL, giving clear alternative paths when this tool is not appropriate.

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 far more than annotations: retry safety with same request id, cost of one city fee credit, immutable history appending, quiet mode behavior, protected place restrictions, and retirement effects. Aligns with and enriches destructiveHint and idempotentHint without contradiction.

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?

Long and dense, but no sentence is wasted. The structure is slightly sprawling – paid acts, room #454, and restrictions are interleaved rather than grouped – but it front-loads the core purpose. For the complexity, this is acceptable.

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?

Covers all behavioral nuances: costs, retry constraints, history, gazette flow, restore-before-edit rule, and a pointer to the full catalog. With no output schema, nothing essential is missing. An agent can confidently invoke this tool 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 covers only 14% of parameters with descriptions, but the description explains every parameter in prose: quiet, front_matter_thing_ids, drawing variants, city_credit_request_id, and boolean permission switches. It compensates fully for the schema 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?

Description opens with 'As the owner, edit one place' – a specific verb, resource, and actor. It clearly distinguishes this from siblings like thing_edit by targeting places, and the scope of free vs paid edits is explicitly stated. Even without naming siblings, 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?

Provides explicit conditions for when to use paid lifecycle acts (rename, retire, restore) vs free edits, including prerequisites for each. Gives a special instruction for Room #454 to call browse first, and states that places with an open sale offer cannot be edited. This is actionable guidance with clear 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?

Beyond annotations (destructiveHint=true, idempotentHint=true), the description adds rich behavioral context: the bounded two-hour recovery period, terminalization, market-first cancellation, and the rule that late finality cannot transfer a reused thing. This goes well beyond what annotations alone 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 core action is front-loaded, but the description includes extra meta-information about the full catalog and a URL for finding help, which is tangential to the tool's usage. This adds length without directly helping an agent decide when or how to invoke the 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 single-parameter tool with no output schema, the description covers the essential conditions and side effects (ownership transfer, recovery window, cancellation behavior). It doesn't describe the return format, but that's not critical for a tool with such a focused purpose.

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 only offer_id with 0% description coverage. The description clarifies that offer_id refers to the payment_pending world offer being rechecked, giving meaning beyond the schema. Since it's a single, required integer, the description sufficiently explains its role.

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 action: rechecking a payment_pending world offer against finalized Base records, with the outcome being completion of ownership transfer if valid. It clearly distinguishes from siblings like payment_attempt or cancel_world by focusing on reconciliation of an existing pending offer.

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 scenario for using this tool is clearly implied: when a buyer or seller needs to recheck a payment_pending offer. It doesn't explicitly name alternatives or exclusions, but the context makes it apparent this is for post-payment verification, not initial payment (payment_attempt) or cancellation (cancel_world).

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 extensive behavioral context beyond annotations: it charges a fee, creates a new revision, preserves omitted fields, never rewrites older revisions, and requires credit preflight. This complements the annotations (destructiveHint=true, idempotentHint=false) and clarifies the mutation semantics in detail.

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 dense but every sentence carries necessary information. It front-loads the core purpose and fee, then covers parameter semantics, constraints, and payment flow in a logical order. There is no redundancy or 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?

Given the tool's complexity (9 params, conditional constraints, payment flow), the description is remarkably complete. It covers all parameters, constraints, prerequisites, and even provides recovery pointers (front door, catalog). Though there's no output schema, the description does not need to detail return values for an agent to call this 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 44%, the description compensates thoroughly. It explains the behavior of each parameter: omitted fields keep current values, constraints on description length, traits uniqueness and count, recipe total limits, drawing shape requirements (null/REFUSE/pixel), drawing_variants replacement semantics, and the credit request ID usage. It adds meaning far 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 states a specific action ('Revise a kind you own') with a clear resource and fee ('exact $1 city fee'), and differentiates from creating a kind by implying ownership. It is specific and immediately tells an agent what this tool does.

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 explains when to use it (revising a kind you own), conditions (open sale offer prevents revision), and a required prerequisite (call credit_preflight before confirming credit use). It doesn't explicitly name alternatives like invent_kind, but the context is clear and the instructions are actionable.

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 destructiveHint=true, but the description does not explain what destructive effects might occur; it focuses on creation and deduplication. It does add useful behavioral context about quotas, replay handling, response codes, and the reading-cost meter, which goes beyond the annotations. However, the lack of any mention of destructive potential, despite the annotation, leaves a gap in transparency.

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 very long and includes tangential instructions about room #454, the Gazette service, and URL fallbacks, which are not essential for the core operation. It is not front-loaded with the most critical information and rambles, making it harder to parse quickly. Conciseness is poor despite being structured in paragraphs.

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?

The description covers the necessary details for typical usage: response codes, quota behavior, and input constraints. It is complete for most calls, but the inclusion of special-case room #454 instructions adds complexity that might overwhelm agents. Still, it does not omit critical return-value or error-handling info, though no output schema exists to fill 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 0%, the description fully compensates. It explains 'place_id' as the location where the note is left and 'body' with constraints on length, allowed characters, handling of whitespace, and refusal of empty strings. This adds meaning beyond the schema's basic type/length declarations.

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 begins with a clear, specific action: 'Leave a public note in place_id.' It names the exact resource and the nature of the operation, distinguishing it from sibling tools like 'look' or 'browse' which are read-oriented. The verb 'leave' and noun 'public note' are unambiguous, and the context of standing in the place adds situational specificity.

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 explicit conditions for use: the user must be standing in the place, which must be theirs or open to notes, and it outlines quota limits and replay behavior. It also references alternative tools ('front_door') and special procedures for room #454, making it clear when to use this tool vs. others and what prerequisites exist.

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, openWorld, idempotent, non-destructive), the description adds crucial behaviors: rate limits ('burst 12 searches and regains one every 5 seconds'), result format ('body-free outlines with exact total item and UTF-8 body-byte counts; not relevance-ranked'), and pagination mechanics ('Retain the first-page change_marker while using before...'). This far exceeds what annotations alone provide.

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 dense but every sentence earns its place: it covers purpose, defaults, constraints, rate limits, result format, pagination, and pointers to further help. It is front-loaded with the main purpose and structured logically from operation to edge cases.

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 6 parameters and no output schema, the description covers essential operational details: return format, pagination strategy, rate limiting, compatibility constraints, and where to find more tools. 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 only 33%, so the description compensates heavily. It explains defaults for mode, type, and limit, constrains q to 1-256 UTF-8 bytes and words mode to 16 simple words, clarifies maker filtering and its incompatibility with type=note, and describes the use of 'before' for pagination. This adds meaning the schema leaves implicit.

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 ('Search') and resource ('current public notes and active things') with a clear ordering ('newest-first date order'). It also lists defaults, which fully differentiates it from any sibling that might do related lookups. This is not a tautology and precisely conveys the tool's role.

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 clearly implies when to use search (to find public records by query) and provides constraints like 'maker cannot be combined with type=note'. It also points to the full catalog and the front_door tool for orientation, giving an agent context on alternatives, though it does not explicitly state 'use this instead of X'.

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 indicate idempotentHint and destructiveHint, and the description reinforces idempotency by stating that repeats return the existing signature without extra cost. It also adds atomicity of joining and signing, separate signing per party, and daily quotas, which are not covered by annotations. No contradictions found.

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 front-loads the core purpose, and the rest is organized with periods, covering conditions, idempotency, quotas, and fallback links. Some tangential navigation info (full catalog, front door URL) is included but still useful for lost agents, making it slightly longer 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?

Given the simple schema and lack of output schema, the description covers the essential behavioral context: prerequisites, atomicity, idempotency, and quotas. It does not specify the return value for a new signature, but the tool likely returns a simple confirmation, and the description is otherwise thorough for a write operation.

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 carries the full burden for explaining the parameter. The description implies that agreement_id identifies the agreement to sign, but it never explicitly states what the parameter is or its format. This is a gap for a single required parameter.

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 ('Sign'), resource ('public agreement'), and scope ('as yourself'), and distinguishes itself from siblings like open_agreement_accession by clarifying that signing is separate from opening accession. It also specifies atomic joining and signing, which adds clarity.

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 explicit conditions for use: you must be a named party or a later signer after the original author opens accession. It implies the alternative use of open_agreement_accession for the author, and mentions daily quotas that might affect when to call. However, it does not explicitly name alternative tools or say 'use X instead'.

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 discloses significant behavioral details beyond annotations: editing appends immutable history on real changes, no-op appends nothing, selection persists across transfer, and typed things enforce specific drawing rules. It explains side effects and constraints clearly. No contradiction with annotations (destructiveHint=true) — history appending is consistent.

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 but logically structured, front-loading the core 'edit one active thing' and 'send thing_id plus at least one changed field'. However, it includes meta-guidance like 'Full catalog: /api/tools' and 'Lost? Read the city front door' which are not directly about this tool's functionality. These could be trimmed for conciseness without losing tool-specific 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?

The description covers all essential aspects for calling the tool: required field, parameter semantics, drawing rules, constraints (owner, active, no sale offer), and history behavior. It does not specify the return value (no output schema), which is a minor gap, but the complexity of the drawing logic is fully addressed. Overall, it is sufficiently complete for an agent to use 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 only 38% schema description coverage, the description compensates thoroughly. It explains name length and safety, body size limits, open_to_use as boolean, the exact drawing shapes (null, REFUSE, pixel object), drawing_description constraints, and drawing_variant_name selection behavior. It also clarifies the interplay between drawing and drawing_state/description via the conditional schema. This is a strong compensation for low schema 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 clear verb (edit), resource (thing), and scope (one active thing, owner-only). It distinguishes from sibling tools like place_edit or make by specifying the resource type, and the title matches. It's specific and not a tautology.

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 provides constraints: must be the owner, thing must be active, and a thing with an open sale offer cannot be edited. It also differentiates typed vs untyped things. However, it does not explicitly name alternatives or state when to use this tool over siblings like revise_kind or make. The 'Full catalog' and 'Lost?' pointers are meta, not direct 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?

Even with annotations already marking the operation as non-read-only, destructive, and idempotent, the description adds substantial behavioral detail: variant preservation rules, refusal instead of silent fallback, conflict behavior on concurrent changes, no-op idempotency, and conditions that block the upgrade. It also explicitly states when the thing is not changed.

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 but dense, front-loading the core purpose and then walking through edge cases in a logical order. The final catalog and 'front door' navigation sentence is only loosely related to the tool itself, which prevents a perfect score.

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 the description does not state the success return value, but it covers the invocation requirements, variant selection, conflict handling, retry behavior, and blocking conditions comprehensively. The missing return shape is a minor gap given how much operational context is provided.

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 description greatly enriches the drawing_variant_name parameter's meaning by explaining what happens when the exact variant is absent, how null selects the base, and how retries behave with the requested selection. thing_id needs no further explanation beyond its name and the 'thing' context, and the schema already constrains its type and 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?

The description opens with a specific action and resource: as owner, adopt a typed active thing's latest kind revision. This clearly distinguishes upgrading a thing from generic editing (thing_edit) or revising kinds (revise_kind) without needing to inspect 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?

The description gives explicit context for when the tool applies (owner, typed, active, latest revision) and states exclusions: untyped things and things with open sale offers cannot be upgraded. It does not name a specific sibling as the alternative for the excluded cases, so it falls just 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 discloses many behavioral details beyond the annotations, including that nested places move with a place, home clearing with a private attention line, blocking conditions, price rounding, and the five-minute payment window for claim. These go well beyond the readOnlyHint=false and destructiveHint=true annotations, giving the agent a strong sense of side effects and constraints.

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 dense and covers a lot, but it is organized by action with the default first. It avoids fluff but is somewhat lengthy and run-on, mixing multiple constraints in one sentence. It could be broken into clearer paragraphs, but it is still efficient and front-loaded with the most common case.

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 complexity of four actions and eight parameters with no output schema, the description covers all action requirements, edge cases like blocking, and response details (e.g., private attention line). It does not explicitly state return values for each action, but it provides enough context for an agent to call correctly. The lack of output schema means the description carries more burden, and it mostly meets it.

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?

Despite 75% schema coverage, the description enriches several parameters: it explains that action defaults to give, specifies which parameters are required per action, clarifies price rounding (already in schema but reinforced), and details the buyer_wallet requirement for claim. This adds meaning that the schema alone does not convey, especially for action-specific usage.

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 clearly states the tool transfers property with four distinct actions (give, offer, claim, cancel), specifying the default action and required fields for each. It is specific about the verb and resource, and the action enum disambiguates sub-purposes, making it easy for an agent to understand what the tool does.

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 provides explicit conditions for each action, such as 'give requires type, id, and to_handle' and 'cancel requires offer_id and is available only to the seller outside an active payment window.' However, it does not contrast with sibling tools or state when to prefer this tool over alternatives, so it misses explicit exclusions. The reference to the front door and catalog is a fallback, not a comparative guideline.

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 carry destructiveHint=true and idempotentHint=false; the description reinforces 'Permanently' and adds specific behavioral traits: the strict exact-name matching with refusal behavior, and the open-sale blocker. No contradiction with 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?

Dense but not bloated; every sentence adds value (permanence, name matching, sale restriction, recovery path). The core action is front-loaded. Slightly long but each clause 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 tool with no output schema, the description covers the purpose, prerequisites, failure conditions, and a fallback for lost context. Missing only explicit alternative-tool routing, which is a minor gap given sibling count.

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 carries the burden. It clarifies thing_name as the exact current name (with mismatch refusal) but gives no additional semantic detail on thing_id beyond the schema's integer/minimum constraints. 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?

States a specific verb (withdraw), resource (thing), and scope (owned, active, permanent). The action is clearly distinguishable from siblings like transfer or thing_edit without needing to inspect 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?

Gives clear conditions for use: the exact-name requirement, the refusal on mismatch, and the open-sale restriction. Provides a recovery path via front_door for lost context. Does not explicitly name alternative tools, but the constraints are concrete and actionable.

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