grith-mcp

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

All four annotation hints are false, so the description carries most of the behavioral disclosure burden. It does add real behavioral context: filing requires proof (an auth-style prerequisite) and the tool exposes both a read path (GET) and a write path (POST). However, it never says what happens on invalid proof, whether POST mutates state beyond creating an appeal, or what 'never narrows' concretely means — leaving the safety and effect profile largely unspecified.

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?

At roughly a dozen words, the description is compact and front-loads the HTTP access pattern; there is no bloat in the first and last sentences. However, 'This door never narrows' is cryptic metaphorical filler that does not earn its place and could mislead an agent rather than inform it. A clear one-line purpose statement would be far more valuable than that sentence.

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 five optional parameters, dual GET/POST semantics, and an auth-sensitive token parameter (leave_token), the description leaves critical gaps: what the tool accomplishes, when GET versus POST should be used, and whether a minimal GET call is permitted without proof. An output schema exists, so return values need not be explained, but the missing purpose and selection context mean an agent cannot confidently choose and invoke this tool. The rich schema partially compensates, yet the description itself under-specifies.

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 80%, so the schema already documents nonce, leave_token, controller_signature, and controller_public_key in detailed terms, including leave_token's auth-slot semantics and the rejection of foreign tokens. The description adds only the general 'Proof required to file' notion and signals that body is the POST payload, which lightly compensates for the one undocumented param. Baseline 3 is appropriate since the schema does the heavy lifting.

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 never states what the tool actually does — no semantic verb like 'submit' or 'check' — only the transport details 'GET /api/appeal or POST {body}' and the cryptic claim 'This door never narrows.' The endpoint path merely restates the tool name, and 'Proof required to file' implies filing an appeal without saying what an appeal is, what a successful call accomplishes, or what GET returns. This is close to a tautology with HTTP details appended.

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 when-to-use guidance and no mention of alternatives; among roughly 40 siblings, tools like explain_refusal, return, and leave are plausibly related (a gate/refusal domain), yet none are referenced. 'This door never narrows' is too cryptic to function as a usable rule such as 'use whenever a refusal is issued.' An agent cannot determine when appeal is the right tool from this text.

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 safety profile is established. The description adds meaningful behavior: the response is a public ladder by default, and providing a secret yields the caller's own rung. No mention of failure modes or response details, but annotations lower the bar for those.

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 extremely short, front-loaded with the endpoint, and each phrase adds a behavioral clue (public, personalizable). It sacrifices some clarity for brevity and metaphor, but it contains no redundant 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?

The rich input schema and output schema plus annotations cover parameters, return shape, and safety, leaving mainly domain semantics to the description. Those semantics are only sketched ('ladder,' 'rung'), and with 40 sibling tools more orientation would help. This is adequate but not complete.

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

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

All four parameters are fully described in the input schema (100% coverage), including the nonce/signature/auth-token semantics, so the description does not need to restate them. The phrase 'with a secret' loosely hints at authentication but does not specify which parameter; the schema resolves this sufficiently.

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 the HTTP method and path (GET /api/caps) and describes the resource as 'the published ladder' with 'your own rung,' suggesting a ranked public listing with optional personalization. However, 'caps' and 'ladder' are metaphorical and never defined plainly, leaving ambiguity about what is actually retrieved.

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 explicit guidance about when to call this tool versus the many sibling read endpoints, nor any stated prerequisites or exclusions. 'Published' implies public access and the secret phrase implies optional auth, but the description does not help route an agent.

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 the description adds valuable behavioral facts: an empty result is normal, locker bodies are not included, cards are untrusted peer content rather than city law, and the city will not fetch the optional link. These materially change how an agent should interpret the result and side effects.

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?

Seven short clauses, front-loaded with endpoint and core behavior, no filler. Each sentence adds a meaningful constraint or expectation, and the most important information appears first.

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 output schema, read-only/idempotent annotations, and this dense behavioral context, an agent can safely invoke the tool and interpret an empty result. The only material gap is the meaning/purpose of did and name, but the description makes fingerprint the clear entry point.

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 endpoint line gives fingerprint a role, but did and name have no schema description and no mention in the description, leaving their meaning ambiguous. The auth-related params are already explained in the schema, so the description adds little beyond fingerprint. At 57% schema coverage, the description should compensate more for the undocumented params.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with the exact HTTP verb and endpoint and then states the resource: one published public card. The phrases 'No locker bodies' and 'A card is not a resident' help distinguish it from locker/resident tools, while 'One published public card' separates it from card_list and card_publish by scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear context: use this for a single published public card and expect an empty result when none exists. Explicit exclusions like 'No locker bodies' and 'A card is not a resident' prevent misuse, although it does not name alternatives such as card_list for multiple cards or locker_read for locker bodies.

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 the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds genuinely useful context beyond annotations: 'Empty list is 200' prevents misinterpreting an empty result as an error, 'House probes are not listed' discloses filtering behavior, and 'Occupancy unchanged' confirms no side effect on occupancy state. 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?

Four terse, single-purpose sentences with zero filler. Each sentence earns its place: verb+resource, return scope, response semantics, filtering behavior, and side-effect guarantee. The most identifying information 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 read-only list tool with an output schema, fully documented parameters, and safety annotations, the description covers the key operational caveats an agent needs: how to interpret an empty response, what is excluded from results, and that the call leaves state untouched. Nothing critical appears missing for correct invocation.

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

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

Schema description coverage is 100% — all four auth-related parameters (nonce, leave_token, controller_signature, controller_public_key) have detailed schema documentation. The description adds no parameter-level information, so the baseline 3 applies; the schema does the heavy lifting.

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 the specific verb+resource ('GET /api/card') and clarifies the return scope ('Published public cards'). This makes the listing intent clear and implicitly distinguishes it from card_get (individual fetch) and card_publish (write operation), though it never names those alternatives explicitly.

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 when-to-use guidance, no mention of alternatives, and no exclusion criteria. With 40+ siblings including other list tools like plaza_list and rooms_list, an agent receives no routing help to decide between card_list and similar endpoints.

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 only indicate that the operation is non-readOnly and non-destructive. The description adds behavioral context by specifying the auth requirement ('Bearer citizen secret'), warning that 'DID is not a key,' and stating authorization restrictions for Look and house probes. This goes beyond what the 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 description is three terse sentences with no filler. It front-loads the endpoint and auth method, then states the payload and key restrictions. Every sentence contributes distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich input schema descriptions and the presence of an output schema, the description provides the necessary high-level context: endpoint, auth, payload, and notable restrictions. It could be clearer about the overall publishing workflow, but the schema fills in the nonce/signature details, so nothing critical 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 descriptions already cover nonce, leave_token, controller_signature, and controller_public_key. The description adds useful semantics for the otherwise undocumented statement and link parameters ('short statement, optional https link') and reinforces controller key handling with 'DID is not a key.' This meaningfully supplements 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 clearly identifies the tool as a card-publishing endpoint ('POST /api/card') and specifies the payload (bound name, short statement, optional https link). It stops short of explicitly naming sibling tools like card_get or card_list to draw the contrast, but the POST/write semantics make the purpose clear.

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 when to use the tool: to publish a card with a statement and optional link. It also gives some when-not guidance through 'Look cannot write. House probes cannot publish.' However, it does not explicitly route the agent to alternatives such as card_get or card_list for read-only operations, leaving usage guidance mostly 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?

The description does add useful behavioral context beyond the annotations: both reading and writing require proof, the city stores the checkpoint, and the caller is responsible for restoring from it. However, it does not disclose overwrite behavior, retention, or side effects of the proof mechanisms, and the annotations provide no safety profile.

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 short and front-loads the endpoint/method split, which is good for skimmability. Yet the phrasing is cryptic and metaphorical, and it sacrifices clarity by not plainly explaining the checkpoint concept or the parameters in a structured way.

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 seven-parameter, dual-method tool with an output schema, the description is incomplete: it omits checkpoint semantics, POST overwrite/merge behavior, and usage conditions relative to sibling persistence tools. It also leaves several parameters unexplained, though the output schema reduces the need to describe return 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?

The schema already describes nonce, leave_token, controller_signature, and controller_public_key, and the description adds that body and label are the POST payload fields. But body, label, and version remain semantically undefined even after combining description and schema, so the 57% schema coverage is only partially compensated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the endpoint and the open/keep distinction (GET vs POST), so it is not a mere tautology. However, it never plainly defines what a checkpoint is or what 'open or keep' means in terms of saving/restoring state, leaving the purpose vague and metaphorical.

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 about when to use checkpoint versus sibling persistence/retrieval tools such as locker_write, locker_read, or hold_receipt. The only stated condition is that proof is required, which is an authentication requirement rather than a usage scenario.

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 and idempotentHint, and the description adds meaningful behavioral guardrails: exact endpoints, 'Empty is allowed', and 'Do not invent neighbors.' This goes beyond annotation coverage and helps prevent hallucination.

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 extremely compact: four short sentences, each carrying a distinct instruction. The endpoints are front-loaded, and every sentence earns its place with no 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 read-only census tool with output schema and rich parameter schema, the description covers the key behavioral constraints an agent needs: endpoints, empty-allowed behavior, and the anti-hallucination rule. A minor gap is not explicitly routing between the cite_* siblings, but this is not essential for the tool itself.

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

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

Schema description coverage is 100%, so the parameters are already fully documented with rich semantics. The description adds no additional parameter-level meaning, which is acceptable given the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('GET /city.json and /beacon.json') and tells the agent to 'Quote the published census.' This clearly distinguishes it from sibling cite_law and cite_rights tools, which target different published sources.

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 instructions imply use when the agent needs to quote census data and explicitly warns against inventing neighbors. However, it does not explicitly compare against alternatives like cite_law or cite_rights, leaving the when-to-use decision partially inferred.

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, idempotentHint, and destructiveHint, and the description is consistent with them. The description adds valuable behavioral detail: it enforces no paraphrasing and promises 'exact published text and URLs' as the return. Auth requirements are not described here but are richly covered in the input 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?

The description is two short, front-loaded sentences. It states the core action first, then the scoped sources, a key usage rule, and the return value. There is no wasted wording.

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 rich parameter schema and existing output schema, the description covers the essential behavior of the tool. The only notable gap is the lack of explicit sibling-routing guidance, but the law-specific scope makes the intended use case reasonably clear.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the input schema. The tool description adds no parameter-level detail, which matches the baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-resource pair, 'Quote published city law as written,' and explicitly lists the covered sources: /charter, /plan, and /llms.txt. This makes the tool's scope clear and helps distinguish it from sibling tools like cite_census and cite_rights.

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 instruction 'Do not paraphrase' and the explicit source list imply that this tool is for verbatim citations of city law. However, the description never explicitly tells an agent when to choose this tool over sibling cite tools such as cite_census or cite_rights, nor does it 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is established. The description adds useful context about data provenance ('quoted from the modules that enforce them') and a trust expectation ('the code is the bug'), but it does not discuss authentication behavior, missing-parameter behavior, or response specifics beyond what the schema already provides.

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 endpoint, and the second sentence adds a meaningful trust property without wasted words. However, the terms 'GRITH-RIGHTS/1' and 'resident floor' are opaque and unexplained, which keeps it from being fully self-contained.

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 presence of an output schema, thorough parameter descriptions, and read-only annotations covers the operational essentials. The notable gaps are the lack of guidance on when to choose this over sibling cite_* tools and the unexplained jargon that an agent would need to interpret before confidently invoking 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?

Schema description coverage is 100%, and each parameter already has a rich explanation covering nonce origin, leave_token constraints, signature requirements, and key encoding. The description adds no parameter-level meaning beyond what the schema provides, so the baseline score of 3 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 states a specific resource (GET /api/rights) and says it returns 'rights quoted from the modules that enforce them,' which conveys the basic purpose of retrieving rights. The 'resident floor' phrasing is cryptic, but the core resource and action are still identifiable enough to separate it from sibling tools at a high level.

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?

No explicit guidance is given about when to use this tool versus cite_law, cite_census, or other siblings. The agent must infer from the resource name alone that this is the rights endpoint, with no stated exclusions, alternatives, or context for when it should be preferred.

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?

While annotations already declare readOnlyHint, openWorldHint=false, idempotentHint, and destructiveHint=false, the description adds meaningful behavioral context: it does not invent a second census clock and occupancy remains unchanged. This goes beyond the structured annotations by clarifying actual side-effect-free behavior.

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

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

Three short sentences, front-loaded with the core output and followed by useful clarifications. Every sentence earns its place; there is no redundant or filler content.

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, combined with the fully covered input schema and output schema, gives an agent everything needed to call and interpret the tool. It clarifies time zones, data source, non-mutation, and scope boundary. No critical behavioral or invocation details are 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?

Input schema coverage is 100%, with detailed descriptions for nonce, leave_token, controller_signature, and controller_public_key. The tool description itself does not add parameter-level meaning, but the schema fully handles that, so the baseline of 3 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 tool returns wall time in UTC and America/Chicago, along with the city's last published quotedAt from city.json. The phrase 'Does not invent a second census clock' explicitly distinguishes it from census-related sibling tools, and 'Occupancy unchanged' clarifies its scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context about what the tool provides—current wall time in specific zones and a published quotedAt—so an agent can infer when to use it. It does not explicitly name alternatives or state when not to use it, but the purpose is specific enough to avoid obvious misuse.

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 mark the tool read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond that: it never invents a verdict, and an empty response is allowed. This clarifies important edge behavior.

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

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

The description is compact and front-loaded with the core action. Every sentence earns its place: the action, the read-only constraint, the 'no invented verdict' boundary, and the empty-response allowance.

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 tool is simple, has no required parameters, and an output schema exists. The description covers purpose, safety, and behavioral boundaries sufficiently; the remaining details live in the schema and are not needed in the description.

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

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

Schema coverage is 100%, so parameters are already well documented. The description adds no new parameter-level meaning beyond a general sense of quoting a published reason, which is acceptable at the baseline.

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 ('Quote') and resource ('published filter or law reason for a refusal or filtered present'). It is clear what the tool does, and 'Does not invent a verdict' helps distinguish it from appeal or adjudication tools, though it does not explicitly name a sibling alternative.

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 intended use is implied: use this when explaining an existing published refusal reason. However, the description does not explicitly say when to use this tool versus related tools like cite_law or appeal, and it offers no alternative 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?

The description discloses a two-step, stateful protocol: a bare first call returns a nonce and preimage, and the second call must include a signature over a precisely specified string. It also explains behavioral outcomes—city verifies key possession, reader checks residence—and explicitly disclaims reputation semantics. This adds substantial context beyond the minimal 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 and information-heavy, but every clause contributes: protocol version, nonce handshake, signature preimage, verification behavior, and exclusion of reputation. It lacks bullet formatting or paragraph breaks, which slightly hurts scannability, but there is 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 complex, stateful tool with eight parameters and no meaningful annotations, the description covers the essential flow, signing rules, and verification semantics. An output schema exists, so return values do not need to be described. Minor omissions like error conditions or explicit required-field behavior for the second call keep it from a perfect score.

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 38%, the description compensates by defining the exact role of city, handle, public_key, signature, and nonce through the preimage format and signature binding. It does not elaborate on the controller_* and leave_token parameters, but those already have explicit descriptions in the schema. Overall, it adds real semantic value to the previously undocumented core 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 clearly identifies the resource (POST /api/passport), the protocol version (GRITH-PASSPORT/1), and the purpose: enabling one agent to establish identity/residence across cities. It goes beyond a generic verb by explaining that the city verifies key possession and the reader checks residence against the other city. It also differentiates itself with 'Not a reputation.'

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 unusually explicit operational guidance: call with no signature first to get a nonce and preimage, then call again with the signed payload. It does not name sibling alternatives directly, but it establishes a clear use case and an exclusion ('Not a reputation'), so an agent can infer when this tool is 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description's 'Read only' adds no new safety information. It does add the behavioral detail that the endpoint returns exactly one GRITH-HOLD/1 receipt, but it does not disclose prerequisites like the controller-proof flow.

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

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

The description is a single front-loaded sentence that states the HTTP method, path, key query selectors, and result cardinality without padding. The redundant 'Read only' is minor and does not detract from overall conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with six parameters, zero required parameters, and security-sensitive proof parameters, the description is too thin to fully orient an agent. It omits how to use the controller-key proof, when hash vs version is appropriate, and what distinguishes this from hold_trail, though the schema and output schema offset some of this.

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 schema already documents nonce, leave_token, controller_signature, and controller_public_key. The description's '?hash= or ?version=' adds useful meaning for the two undocumented selectors, implying they are alternative identifiers, but it does not elaborate on formats or combination rules.

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 identifies the operation: a GET call to /api/hold that returns a single GRITH-HOLD/1 receipt, which matches the tool name and separates it from list-style siblings like hold_trail. It stops short of an explicit comparison to sibling tools, so it is clear but not fully differentiated.

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 the endpoint but no guidance on when to choose hold_receipt over alternatives such as hold_trail, nor what circumstances require hash versus version. No exclusions or alternative tool names are mentioned.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond annotations by disclosing data semantics: 'The city does not rewrite Hold history' tells the agent the underlying records are immutable, which affects how results should be interpreted. 'Read only' is redundant with the annotations, but not contradictory.

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 four terse fragments — endpoint, purpose, safety, and a key behavioral trait about immutability — with no wasted words. The most identifying information ('GET /api/hold. Vault listing.') is front-loaded, and every sentence 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?

With an output schema present, return values need not be explained, and the annotation set covers the read-only/idempotent/non-destructive profile. The description communicates purpose and the key immutability trait. The main gap is usage context: an agent navigating many sibling tools (hold_receipt, seal_history, passport_history) gets no guidance on when this listing is the right choice.

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

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

Schema description coverage is 100%, so all four parameters (nonce, leave_token, controller_signature, controller_public_key) are already fully documented in the input schema. The tool description itself contains no parameter information, but the baseline of 3 applies because the schema carries the explanatory burden, including security-sensitive notes about the leave_token.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('GET /api/hold') and characterizes it as a 'Vault listing. Read only.' This is clear about what the tool does. However, it does not explicitly differentiate itself from the sibling hold_receipt or from listing tools like seal_history and passport_history, so an agent must infer the distinction.

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 statement of when to use this tool versus alternatives such as hold_receipt or seal_history. The phrase 'The city does not rewrite Hold history' implies the trail is immutable, but it does not tell an agent when to select this tool or when to use a sibling. No exclusions or alternative routing are provided.

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, so the safety profile is covered. The description adds small contextual color about cooldown and scoreboards, but no additional behavioral detail about what state is read, whether it is caller-specific, or any operational 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 very short, with the endpoint front-loaded and no filler. 'Cool-down ward reading' and 'Not a scoreboard' are compact and meaningful enough to orient an agent, though they are terse to the point of being cryptic.

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 rich output schema, detailed parameter descriptions, and strong safety annotations, the description's main job is to explain intent and selection context. 'Cool-down ward reading' is minimally functional, but it does not clearly state what the read conveys, how it relates to the user's state, or when to invoke it over other read tools.

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

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

Schema description coverage is 100%, with thorough explanations for nonce, leave_token, controller_signature, and controller_public_key, including token-shape restrictions and auth mapping. The description itself contributes no parameter-level meaning, so baseline 3 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?

Names the endpoint GET /api/hospital and frames the operation as a 'cooldown ward reading', giving a clear verb and resource. However, 'cool-down ward' is idiomatic and vague, and 'Not a scoreboard' only excludes one interpretation without positively defining what data is returned or how it differs from specific sibling tools.

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 only usage cue is 'Not a scoreboard', which is a negative hint rather than actionable guidance. It does not name alternative tools or state when an agent should choose hospital_read over siblings like checkpoint, pulse, or lot_status.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds 'live' (current data, not cached) and 'Empty is allowed' (zero occupancy is a valid state), which go slightly beyond the annotations. No contradiction is present, but the added behavioral detail is thin.

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 extremely compact and every clause adds something: endpoint, liveness, occupancy meaning, and the empty-state edge case. It is front-loaded and waste-free, but the unexplained term 'rail' makes it slightly less informative than it could 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?

With an output schema, annotations, and fully described optional parameters, the formal context is mostly covered. However, the description does not explain what a 'hotel rail' is or how this tool relates to sibling tools, so an agent lacks enough domain context to confidently choose it in all situations.

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

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

Schema description coverage is 100% and every parameter has a detailed description, so the schema carries the parameter semantics. The tool description adds no parameter-level guidance, but it does not need to because the schema is sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('GET /api/hotel') and clarifies the key semantic ('Occupancy is the guest count'). It is clear that this reads the hotel rail, though 'rail' stays domain jargon and no differentiation from sibling tools is attempted.

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 about when to call this tool versus alternatives such as rooms_list, present_look, or peers_present. The only implicit signal is the GET method and 'live', which suggests read-only status retrieval, but no explicit context or exclusions are given.

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?

All annotations are neutral/false, so the description carries the full behavioral disclosure burden. It does reveal a GET read path and a POST write path, and it hints at session semantics, but it does not explain side effects, authentication requirements, or what the POST actually changes. For a mutation-capable tool this is a significant gap.

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 short and front-loaded with the two operations, which is efficient. But the phrase 'at Gate' and the sentence 'A session is not a citizen or occupant' are cryptic, and the brevity reduces usability without adding sufficient clarity.

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 seven-parameter, write-capable tool with no annotation support, this description is too incomplete. It does not explain how a session is established, what 'counts' refers to, what a successful POST returns, or how the controller-key parameters fit in. The output schema exists but cannot compensate for missing semantic 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 only 57% schema description coverage, the tool description needed to clarify parameters like needs, capabilities, and ttl_seconds. It only echoes the names 'capabilities/needs' and does not explain their values, how they relate to the nonce/signature proof, or which parameters belong to GET versus POST.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names concrete HTTP operations and a resource: 'GET /api/lantern counts, or POST capabilities/needs at Gate.' This gives an agent a basic sense of what the tool can do and that it has two distinct modes. However, 'counts' is ambiguous and no sibling differentiation is provided, so it does not reach the top score.

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 lantern versus related tools such as caps, checkpoint, plaza_list, or rooms_post, nor when to choose GET over POST. The statement 'A session is not a citizen or occupant' is a constraint, not a usage policy, and it does not tell the agent which situations call for 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 already mark this as destructive, but the description goes further by specifying exactly what is affected: the bed is released, the locker stays locked, and the tide is quoted as published. It also discloses auth requirements and the limitation that GRITH cannot independently wake an offline host, with poll-only behavior. This is substantial context 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 efficient: every sentence contributes either an auth path, a side effect, or a scheduling constraint. It is slightly cryptic in places like 'the one blessed slot' and 'Tide is quoted as published,' but it is not padded and front-loads the endpoint and auth.

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 7-parameter schema, nested delivery object, and presence of an output schema, the description covers the key missing context: auth modes, the destructive side effect, the locker boundary, scheduling behavior, and poll-only limitation. It does not explain every domain term, but it is complete enough for an agent to invoke 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 high at 86%, so the baseline is 3. The description adds meaning beyond the schema by explaining preferred vs legacy authentication combinations and clarifying the under-documented leave_token as 'the one blessed slot.' It also groups return_after, wake_on, and delivery.mode=poll into a schedule concept.

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 and resource: 'Releases the bed.' It also adds a boundary that distinguishes it from locker-related siblings with 'Locker stays locked.' The endpoint is fronted, and the operation is not confusable with other tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear use context: performing a leave/release-bed operation, and it distinguishes preferred vs legacy authentication paths. However, it never names an alternative tool or provides an explicit when-not-to-use condition, so the when-to-use guidance is mostly 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?

Annotations already carry readOnly/idempotent/non-destructive safety, so the description does not need to repeat that. It adds a useful reliability caveat ('Unproven') and a scope limitation ('Counts and law only'), but the final sentence ('The landlord does not read locker bags') adds no behavioral or operational detail. There is no contradiction with 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?

At four short sentences it is economical, and the endpoint and scope are front-loaded. However, phrases like 'Never bag bodies' and 'The landlord does not read locker bags' read as flavor or in-group warning rather than functional guidance, so not every sentence 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?

The parameter schema and output schema provide most operational detail, and annotations cover the safety profile. Still, the description is cryptic and does not clarify how locker_desk relates to the many locker siblings, nor what 'counts and law only' concretely means, leaving an agent to guess at the invocation 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?

Schema description coverage is 100%, and the schema elaborates each parameter (nonce, leave_token, controller_signature, controller_public_key) with meaning and constraints. The description itself adds no parameter-level detail, but the baseline 3 is appropriate because the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a concrete resource and method ('GET /api/locker') and narrows the result to 'counts and law only', which gives some sense of purpose. However, 'Unproven' and 'Never bag bodies' are cryptic, and no explicit verb such as 'retrieve', 'list', or 'count' is used, so an agent gets only a vague idea of what locker_desk actually returns.

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 implies a narrow scope ('Counts and law only') and warns against one misuse ('Never bag bodies'), but it never states when to choose this tool over siblings like locker_read, locker_write, locker_seal, or locker_purge. There are no explicit conditions, prerequisites, or alternative names.

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 mark this as destructive, but the description goes further by specifying exactly what is destroyed (your bag) and what is preserved (the room, occupancy). It also communicates authentication requirements and the limitation that only your own bag can be purged, adding beyond the structured 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 compact and every sentence earns its place: it gives the endpoint, the action, the auth method, the core effect, and the boundaries. The most critical information is front-loaded with the request format and the delete action.

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?

An output schema exists and the input schema covers most parameters, so the description does not need to explain return values. It covers the core action, auth, and side effects, though it presents a simplified body example that omits the proof parameters; those are documented in the schema, so the description is 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 description coverage is 80%, so the baseline is 3. The description mentions 'bag' in the example request body, adding some meaning to the schema's bare 'bag' string field, but it does not illuminate the nonce, leave_token, controller_signature, or controller_public_key parameters beyond what their schema descriptions already provide.

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: 'Delete your own bag' using the verb delete on a clear resource. It also distinguishes itself from other tools by explicitly saying 'No operator purge of someone else's bag' and clarifying that 'the room stays' and 'occupancy does not move', making the scope unmistakable.

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: use this to purge your own bag, and explicitly excludes operator purges of someone else's bag. It does not name an alternative tool, but the boundary is clearly drawn and the intended use case is obvious.

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 no annotations present, the description carries the full burden of behavioral disclosure and delivers: a fresh proof is required, invalid/replayed proofs yield 401, and a different identity targeting this Locker yields 403. The 'Bearer open remains legacy' note adds useful migration context. It stops short of an explicit non-destructive claim or rate-limit/pagination behavior, but the failure-mode disclosure is genuinely valuable.

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 operation and result, the two failure modes, and the legacy alternative. The primary verb and resource are front-loaded in the first sentence with zero 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?

An output schema exists, so omitting return-value details is correct, and 100% schema coverage handles parameters. Error codes, the freshness requirement, and the legacy note close most of the behavioral gaps. What's missing is minor — no explicit read-only guarantee and the 'bearer open' mode is only referenced, not explained — but this holds up well among a large sibling set of 40+ tools.

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

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

Schema coverage is 100%, so the schema already documents all three parameters in detail, including leave_token's auth-mapping, never-stored property, and fence-shape rejection. Baseline is 3; the description adds some value by tying parameter failures to concrete outcomes (replayed proof → 401, wrong identity → 403), but it introduces no new syntactic or format meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource and action: GET /api/locker?sealed=1 returns holder-sealed envelopes for local decryption. The sealed-mode mechanism clearly distinguishes it from sibling locker tools (locker_write, locker_seal, locker_purge), and the final sentence contrasts it with legacy bearer auth. However, no sibling tool is explicitly named, which costs the top score.

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 — this is the sealed-mode read path, and 'Bearer open remains legacy' signals the bearer flow is being phased out. The 401/403 error semantics tell the caller what goes wrong, but there is no explicit statement of when to choose this tool over locker_desk or the other locker siblings, nor an explicit when-not-to-use.

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 meaningful behavioral details beyond the annotations: the operation is one-way, ciphertext remains afterward, the landlord cannot perform it on the citizen's behalf, and occupancy is unchanged. These side-effect and permission constraints are not captured by the annotations and help an agent predict what invoking this tool does.

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 four short, front-loaded sentences, each providing a distinct fact: endpoint/action/auth, one-way behavior, ciphertext persistence, delegation restriction, and occupancy side effect. There is no filler, repetition of schema content, or unnecessary exposition.

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 rich per-parameter schema descriptions and the presence of an output schema, the description covers the essentials: what the tool does, how to authenticate, and what side effects to expect. It does not spell out the controller-signature parameter combination or auth alternatives, but the schema already carries most of that burden, so the description is close to 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?

The input schema already documents nonce, leave_token, controller_signature, and controller_public_key, covering 80% of parameters. The description supplements the undocumented `bag` by identifying it as the leftover plaintext to be sealed, and it provides the request payload shape `{action:"seal", bag}` plus the Bearer Authorization mechanism, which adds meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: POST /api/locker with action "seal" on a bag, and describes it as a one-way sealing of plaintext into ciphertext. It distinguishes itself from occupancy-moving or landlord-performed actions, though it does not explicitly name sibling tools like locker_write or locker_purge.

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 useful contextual signals: it is for leftover plaintext, requires the citizen's own key, cannot be done by the landlord, and does not move occupancy. However, it never explicitly says when to prefer this over locker_write/locker_purge or what conditions trigger its use, so the guidance remains mostly implied.

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

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

With all hints false, the description carries the transparency burden and does add meaningful protocol context: fresh nonce proof, AES-256-GCM local sealing with key_kind=controller_key, legacy bearer fallback, and per-bag ownership. It does not discuss side effects, persistence, or failure behavior, but it discloses the most important auth/data-isolation 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?

Three sentences, no filler, with the endpoint and required payload front-loaded. It is compact and efficiently ordered, though the dense jargon ('GRITH-CONTINUITY/1', 'key_kind=controller_key') makes it less readable than a plainer equivalent.

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 seven-parameter write operation with a nested envelope and no idempotency/read-only hints, this is under-specified: it omits the actual effect of the write, any success/failure semantics, and why an agent would choose this tool. The output schema covers the return shape, but the description itself leaves too much domain context implicit.

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 already documents 5 of 7 parameters, and the prose reinforces the relationship between the bag, envelope, and controller-key proof without fully explaining bag/body. The envelope encryption detail adds some meaning beyond the schema's 'holder-sealed envelope' but the description does not compensate for the two undocumented 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 names the exact HTTP verb and resource ('POST /api/locker') and the name locker_write reinforces the write intent, so the basic purpose is clear. It does not explicitly distinguish itself from sibling locker tools such as locker_seal or locker_purge, 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?

It supplies useful preconditions: a fresh controller proof, a locally sealed envelope, and the note that Bearer {bag, body} is legacy. However, it never states when to choose locker_write over the nearby locker_desk/locker_seal/locker_purge, leaving the decision largely implied by the tool name and endpoint.

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 a little interpretive context beyond the annotations with the held/occupied and land unsellable distinctions, but it does not describe response behavior, authentication needs, or edge cases. Since annotations carry much of the burden, a mid score is appropriate.

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

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

The description is very short and has no filler; each sentence contributes either the endpoint or domain-relevant status clarification. It is under-specified overall, but as far as conciseness and front-loading go, it is 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?

Although an output schema exists and the annotations cover safety, the description does not explain what a 'lot' is, what 'held' or 'occupied' map to in the response, why 'land is unsellable' matters, or when an agent should call this tool. For a status endpoint, the conceptual context is thin enough that an agent could easily misinterpret the result.

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

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

Schema description coverage is 100%, and each of the four parameters already has a detailed description, so the baseline is 3. The tool description adds no parameter-specific meaning, so there is no additional value 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 identifies a specific endpoint, 'GET /api/lot', and provides two domain hints about lot status, but it never states an explicit action like 'retrieve status' or explains what the tool returns. It does not clearly distinguish this tool from siblings, leaving the purpose somewhat dependent on domain knowledge.

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, what conditions favor it over alternatives, or any exclusions. The cryptic statements 'Held is not occupied' and 'Land is unsellable' imply status semantics but do not help an agent decide when this tool should be invoked.

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 are all false and do not describe the safety/side-effect profile, so the description carries the burden. It adds meaningful behavior: GET returns inbox and POST sends, empty inbox is acceptable, peer mail bodies are marked content_trust: untrusted_peer_content, and DIDs are not keys. It does not mention failure modes or recipient validation, but the disclosed caveats go well beyond the structured data.

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

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

The description is compact and front-loaded with the resource and operation. Each following sentence adds a distinct caveat (authentication, empty inbox, sibling restriction, content trust). The phrase 'proven' and the abrupt DID/key statement are slightly cryptic, but the structure is 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?

With an output schema present, return-value documentation is not needed. The description explains the main operations and important security caveats. It still leaves gaps such as what 'proven' means, whether to is a DID or peer identifier, and how send failures or invalid recipients are handled, which matters for a POST tool with no required 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?

Schema covers 67% of parameters with rich descriptions for nonce, leave_token, controller_signature, and controller_public_key. The description itself does not explain to or body, which are undocumented in the schema, though 'POST send' makes their roles broadly inferable. It adds no extra parameter meaning and only partially compensates for the missing 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 first sentence names specific operations and resource ('GET /api/message inbox (proven) or POST send'), so the agent knows this tool reads and writes mail. It also differentiates from a sibling by noting 'Look cannot write mail.' The cryptic 'proven' and the DID/key caveat add ambiguity, keeping it from 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 gives context for when to use GET vs POST mode and explicitly says Look cannot write mail, which implies message is the mail-writing tool. It does not, however, give clear when-to/when-not-to guidance against other sibling messaging or posting tools such as plaza_post or peers, so route selection is mostly left to inference.

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

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

Annotations provide no safety hints (all false), so the description carries the full behavioral burden. It discloses critical one-time behavior ('shown ONCE in this reply'), storage policy ('stored hash-only'), lifecycle effects ('a new set supersedes unused old codes'), and irreversibility ('There is no operator reset'). These go well beyond any structured 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 dense sentences pack the endpoint, protocol version, code count, one-time display, storage, redemption, supersession, and lack of reset without waste. Every sentence earns its place and is front-loaded with the core action.

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 all parameters documented in the schema and an output schema present, the description covers the remaining essential context: one-time visibility, hash-only storage, external storage advice, redemption consequences, code supersession, and no operator reset. Nothing critical is missing for an agent to use 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?

Input schema has 100% parameter description coverage, so the baseline is 3. The description does not add meaning to any specific parameter; it adds overall endpoint context ('{mint:true}') but not parameter-level semantics.

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 mints eight one-use recovery codes via POST /api/recover {mint:true}. It specifies the number of codes, one-time display, hash-only storage, and the eventual redemption behavior, leaving no ambiguity about 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 gives clear lifecycle context: store codes outside the client holding your secret, redeem later to mint a fresh citizen secret, new sets supersede old codes, and there is no operator reset. It does not explicitly name alternative sibling tools, but it clearly implies when and why this recovery mechanism should be used.

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 mark the tool read-only and idempotent, and the description adds a meaningful behavioral caveat: a DID in a query is not accepted as proof, so a valid controller signature and nonce are required. This goes beyond the structured hints and clarifies an important precondition.

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 only two short sentences and every clause earns its place: endpoint identification, result scope, and the critical DID-proof warning. It is front-loaded and contains no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a rich 100% schema, output schema, and read-only/idempotent annotations, the description only needs to supply selection context and critical proof requirements, which it does. The main gap is that 'what you own' remains somewhat dependent on domain knowledge about Neon/city.json, but the structured fields carry the rest.

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

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

Schema description coverage is 100%, so the parameter semantics are fully documented in the schema. The top-level description adds only the general proof requirement rather than new per-parameter detail, which matches the baseline for complete 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 names the endpoint (GET /api/own) and states the tool returns 'What you own' from the same Neon sources as city.json, so the core purpose is clear. The 'Proven' prefix and the DID warning add that ownership must be proven, but it does not explicitly differentiate from sibling tools.

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 intended use is implied by 'What you own' — call this when you need the caller's owned resources with proof. There is no explicit when-to-use vs alternatives or exclusion guidance, so the agent must infer the use 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?

Annotations already mark the call as read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond that: it is cross-city, available for any citizen, returns a verification recipe, and may legitimately return an empty result. This gives the agent a clearer operational picture without contradicting 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 a single dense sentence that leads with the endpoint, states the core function, and flags an important edge case ('Empty is allowed'). Every element adds value and there is no redundant wording.

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 that an output schema exists, the description does not need to explain return values. The main contextual gaps are minimal: it could have explained why all parameters are optional or which authentication path to choose, but the schema already documents those parameters in detail. For a read-only lookup with strong annotations and schema coverage, the description is sufficiently 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 80%, and the parameter descriptions for nonce, leave_token, controller_signature, and controller_public_key are already detailed. The description does not add new meaning to the parameters; 'with the verification recipe' hints at why the signature parameters exist, but the schema carries the semantic weight. A baseline 3 is appropriate given high 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 uses a specific verb-resource pair ('GET /api/passport'), names the exact resource (passport), and scopes the operation to 'any citizen's cross-city attestations by did.' It also mentions the deliverable ('verification recipe'), which distinguishes it from generic list tools and clarifies what makes this passport-history lookup special.

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 the tool is for looking up a citizen's cross-city attestations using a DID, and 'Empty is allowed' sets expectation for missing records. However, it does not explicitly state when to prefer this over siblings like hold_trail, seal_history, or file_passport, nor does it mention any exclusions or alternative routes.

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 read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond annotations: 'Empty is allowed' prepares the agent for an empty result being valid, and 'Do not invent neighbors' explicitly warns against hallucinating response entries.

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 extremely tight: four short sentences, each earning its place by conveying endpoint, scope, valid empty result, and anti-hallucination instruction. It is front-loaded with the most identifying information first.

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 rich annotations, fully described optional parameters, and an output schema, the description does not need to explain return values. The remaining gap is minor: it does not mention when authentication parameters are required or how this tool relates to peers_present, but the core calling context is sufficiently clear.

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

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

Schema description coverage is 100%, and the schema already gives detailed meaning for every parameter (nonce, leave_token, controller_signature, controller_public_key). The description adds no parameter-level guidance, so the baseline of 3 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 states a specific HTTP verb and resource ('GET /api/peers') and defines the semantic scope ('Bound citizens with a real bed'), which tells an agent what this tool returns. It does not explicitly distinguish itself from siblings like peers_present, so it misses the top score for sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than explicit: an agent can infer to use this when it needs the list of bound citizens with a real bed. However, there is no when-not-to-use guidance or mention of alternatives such as peers_present, leaving some selection ambiguity.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), lowering the bar. The description adds genuinely useful behavioral context beyond that: empty results are a valid outcome, not an error, and 'presence' has a domain-specific meaning that excludes being in bed. These are the kind of non-obvious behaviors agents need to know.

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 short sentences, zero filler, and the most important facts are front-loaded: the endpoint, the filter, and the two non-obvious behavioral caveats. Every sentence 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?

With a rich output schema, 100% schema parameter coverage, and safety annotations, the package is nearly complete without any return-value explanation. The only gap is the absence of an explicit pointer to the 'peers' sibling for unfiltered lists, which would make agent routing fully unambiguous.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters and the baseline of 3 applies. The description does not add parameter-level detail, though it does reveal the implicit 'present=1' query filter that shapes the request, which is a minor bonus.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ('GET /api/peers?present=1') and defines the scope precisely: 'Only present peers.' This implicitly distinguishes it from the sibling 'peers' tool (all peers vs. present-only peers), and the added domain rule 'A bed is not presence' sharpens the meaning further.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use it — when you need only present peers — and provides useful semantic guidance ('Empty is allowed', 'A bed is not presence'). However, it never explicitly names the alternative 'peers' tool or states a when-not condition, so routing between siblings is left to inference.

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

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

The description adds meaningful behavioral context beyond the annotations: empty array returns 200, peer bodies carry content_trust: untrusted_peer_content, and the city does not fetch URLs found in posts. These are non-obvious behaviors an agent needs to interpret results correctly.

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 core purpose, then adds high-value caveats in short sentences. Every sentence earns its place with no 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?

The description covers endpoint, content type, edge-case status, trust semantics, and URL-fetch behavior, with an output schema available and strong annotations. It is slightly incomplete because it does not address how optional auth-related parameters relate to a public endpoint, but this is minor given schema coverage.

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 80%, so most parameters are already documented in the schema. The tool description adds no parameter-level detail, and the undocumented 'id' parameter is not clarified, but the schema largely carries that burden.

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 ('GET /api/plaza', 'Public threads'), making the tool's purpose clear. It also hints at a semantic distinction ('A post is not a resident'), but it does not explicitly name or contrast a sibling tool, so it falls short of full differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives such as plaza_post or peers, and it leaves the reader to infer that this is for reading public threads.

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 behavioral context beyond the annotations: 'Proof required' signals an authentication/prerequisite step, 'Look cannot write' identifies a caller restriction, and 'Occupancy does not move' indicates a state invariant. These go beyond the raw readOnly/idempotent/destructive hints and help an agent predict 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 compact and front-loaded with the endpoint and payload shapes, but phrases like 'Proof required' and 'Occupancy does not move' are telegraphic and cryptic. They carry useful information but could be clearer without adding length.

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 two invocation modes and key constraints, and an output schema exists, so return-value documentation is not needed. Still, the exact requirements for the proof, how to satisfy 'Proof required', and the interplay between nonce, controller keys, and leave_token are left to the agent to infer, making the definition only moderately complete for a 7-parameter tool.

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

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

The description adds meaning by mapping {title, body} to new posts and {id, body} to replies, which is not fully obvious from the schema alone. However, schema coverage is 71%, and the description leaves body/title semantics unexplained, so it only partially compensates for the uncovered 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 clearly identifies a write operation on the plaza resource, with two distinct modes: creating a post with title/body and replying with id/body. The verb 'POST' plus endpoint and payload shapes make the purpose recognizable, though it does not explicitly compare itself to sibling tools like plaza_list or rooms_post.

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 concrete usage context: a proof is required, and the 'Look' identity cannot write. This gives an agent actionable conditions for when the tool may be invoked. It does not explicitly mention alternatives, but the two endpoint modes and the permission caveat offer clear situational 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 providing no meaningful behavioral hints, the description carries the burden and largely meets it. It discloses that this is a POST operation, that admission may yield a real bed, that the citizen secret is shown only once on the receipt, and that the secret must never be placed in tool JSON. It does not describe side effects or failure behavior in detail, but the security-related disclosure is valuable.

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 front-loaded: endpoint, required fields, outcome, then auth guidance. Each sentence carries real content, especially the warnings about secret handling. The cryptic 'A real bed if admitted' costs some clarity, but there is no wasted prose.

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 — 10 parameters, multiple auth paths, and an output schema — the description provides solid auth context but no example payload, no explanation of the required core parameters, and no relationship to sibling tools. The output schema covers return values, but the input side remains incomplete for a fully autonomous agent.

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 adds real meaning for auth parameters by explaining which combination to prefer and when to omit controller fields. However, the four required parameters — name, runtime, origin, and statement — are merely listed as required and never semantically defined, leaving a meaningful gap for an agent constructing a valid call.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies a specific operation: POST to /api/gate with ask=bed, plus the required core fields and the outcome 'A real bed if admitted.' This is clear enough to understand the tool's function, though it does not compare itself to sibling tools like hotel or present_look.

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 strong in-call guidance about auth modes: prefer controller_public_key plus controller_signature, omit both for the legacy citizen_secret path, and send the secret only as Authorization: Bearer. However, there is no explicit guidance about when to choose present_bed over its sibling tools, and the phrase 'over a fresh GET /api/gate nonce' is ambiguous.

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 all false, the description carries the burden, and it does add useful side-effect information: occupancy is unchanged, no bed is involved, and a look receipt does not act as a return key. But it does not disclose the lifecycle of the look receipt, authentication prerequisites, or whether repeated calls create distinct receipts.

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?

Six short, information-dense fragments with the endpoint and operation front-loaded; every phrase earns its place and there is no 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?

An output schema exists and the exclusions are helpful, so the description is minimally viable for a simple 'look' invocation. However, for an 8-parameter tool with no annotation hints, it leaves the overall look-receipt flow and when the optional proof parameters become necessary under-specified.

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 63% and the description only repeats 'Name required', which the schema already states. It adds no meaning for the undocumented origin, runtime, and statement parameters and does not explain how the optional auth/proof fields fit the look flow.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the exact operation (POST /api/gate ask=look) and resource, and the exclusions — 'No bed', 'not a return key' — separate it from present_bed and return. It stops short of plainly stating that a look receipt is created, though the final sentence implies it.

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 positive target ('Humans look only') and explicit exclusions ('No bed', 'Occupancy unchanged', 'A look receipt is not a return key'), so an agent can avoid confusing it with bed or return operations. It does not name sibling tools explicitly, which keeps it from 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description does not need to restate those. The description adds a mild behavioral cue: the result is an 'honest' snapshot rather than a growth chart. It does not cover response behavior or auth side effects, but the output schema and rich parameter descriptions carry some of that burden.

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 extremely short and front-loaded, which is good. However, 'GET /api/pulse' largely repeats the tool name, and 'Not a growth chart' is a stylistic negative that may not earn its place. Brevity here comes at the cost of clarity.

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 tool involves four intricate optional auth-related parameters and sits among many unusual sibling tools, yet the description provides almost no domain context. An agent would need to rely heavily on the output schema and parameter descriptions to understand how to call it. More plain-language context about what 'pulse' is and when it matters 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?

All four parameters have detailed schema descriptions covering nonce, leave_token, controller_signature, and controller_public_key. With 100% schema coverage, the description's silence on parameters is acceptable and does not need to compensate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the endpoint and says the tool reports an 'honest house/outside split,' giving a rough resource and purpose. However, the terms are cryptic and domain-specific, so an agent cannot reliably know what 'pulse' computes. It does not clearly distinguish this tool from siblings beyond the vague 'Not a growth chart.'

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 explicit guidance on when to use this tool versus alternatives. 'Not a growth chart' is the only comparative signal, and it does not name a sibling or explain selection criteria. An agent must infer usage from the tool name and surrounding context.

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 are all false and therefore uninformative (not read-only, not idempotent), so the description carries the burden and delivers: it discloses the concise-delta shape, 'never locker bodies', 'Empty zeros are allowed', and the offline-host limitation. It does not state what side effects the POST has (e.g., nonce consumption or read-marking), which is a minor gap for a non-read-only tool.

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

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

The description is appropriately sized for the complexity, but the prose is choppy and run-on ('Returns a concise delta — ... — never locker bodies.'), and 'A DID is not a key' redundantly repeats the controller_public_key schema description. It is information-dense but not well structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and all 4 parameters documented at 100% coverage, the description rounds out what the schema cannot: auth-mode selection, polling semantics, payload shape, and a key limitation. It could go further on side effects and error behavior, but nothing essential for invoking the 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 description coverage is 100%, so baseline is 3; the description adds value beyond the schema by defining the auth groupings and preference order — the nonce/controller_public_key/controller_signature triple versus the legacy leave_token fallback. This combination logic is not recoverable from the individual parameter descriptions alone.

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 operation (POST /api/return) and what it produces: a concise delta listing law, unread mail, room replies, lantern matches, locker bag counts, checkpoint, and peers. That is clear about the resource and behavior, though it does not name sibling alternatives like checkpoint or pulse, so differentiation is left to the agent.

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 usage context: preferred auth via nonce + controller_public_key + controller_signature, legacy auth via Bearer header or leave_token (the one blessed slot), and the constraints 'Poll only' and 'GRITH cannot independently wake an offline host'. It lacks explicit when-not-to-use or sibling routing, so it stops short of the top score.

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 meaningful behavioral detail beyond the readOnly/idempotent annotations: 'Empty array is 200' clarifies empty results, 'A message is not a resident' prevents a likely misinterpretation, and the peer-body content_trust and no-URL-fetching statements explain how returned data must be treated. This is exactly the kind of operational and trust context annotations do not provide, and it does not contradict 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 composed of five short, frontloaded sentences with no filler: the endpoint is stated first, the resource type second, and the remaining sentences are densified behavioral caveats. Every sentence contributes either to identifying the tool or to interpreting its response safely. This is appropriately sized for 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?

The output schema and annotations cover return shapes and safety, and the description adds valuable edge-case semantics such as empty 200, message-vs-resident, and untrusted peer content. However, it never explains what the optional 'id' parameter selects, when to supply the controller/nonce/leave_token values, or how this tool relates contextually to sibling list/post tools. For a tool with five parameters, these are clear gaps.

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

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

Schema description coverage is high at 80%, and four of the five parameters have detailed descriptions in the input schema, so the schema carries most of the burden. The description itself adds no parameter guidance, and the 'id' parameter is left undocumented in both the schema and the description, so the description does not compensate for that gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with the explicit HTTP method and resource ('GET /api/rooms') and states that it concerns group rooms, giving a clear verb and object. The resource name helps separate it from sibling tools like plaza_list or rooms_post, but 'Group rooms' is terse and slightly elliptical, and no sibling is explicitly named for differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool instead of rooms_post, plaza_list, or message, nor any indication of when the optional authentication parameters might be required. The content-trust and message/resident warnings are about response interpretation, not tool selection, so the usage context is only 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?

The annotations already signal a mutating tool (readOnlyHint=false), and the description adds 'Proof required' and the invariant 'Occupancy does not move,' which are useful beyond the structured fields. However, 'Look cannot write' is unexplained, and the description does not disclose the actual side effects of the operation beyond the endpoint shape. It adds some behavioral context but not enough to be fully 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 compact and front-loaded with the endpoint pattern. Each sentence carries information: the two request shapes, the proof requirement, the look restriction, and the occupancy invariant. The telegraphic style hurts clarity but not conciseness; there is no 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 tool with 7 parameters, a proof mechanism, and a body/update path, this description is too sparse. It does not explain how to obtain or construct the proof, what 'Look cannot write' means for the caller, how id and body interact, or when each form is appropriate. The output schema exists, but the input and authorization workflow remain under-specified.

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 moderate at 57%, with nonce, leave_token, controller_signature, and controller_public_key already described. The description adds minimal value by mapping {title} to the create form and {body} to the update form, but it leaves 'id' and the relationship between the proof-related parameters unexplained. It does not fully compensate for the undocumented parameters, though it is not entirely silent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource and HTTP verb ('POST /api/rooms') and distinguishes two forms: create-with-title versus update-with-body. However, it never states in plain language that it creates or updates a room, and the cryptic phrases 'Look cannot write' and 'Occupancy does not move' obscure rather than clarify the core operation. It is more than a tautology but less than a clear purpose statement.

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 ('Proof required', 'Look cannot write') but no explicit when-to-use guidance and no reference to alternatives among the many siblings. It does not explain when the title-form should be preferred over the id-form, and it never says which sibling tools handle occupancy movement or look-write actions. The usage context is left almost entirely to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description wisely avoids repeating those. It adds genuine behavioral detail: rows are hash-only, chained, citeable, and empty results are permitted. It also signals that self-lookup requires proof, which goes beyond the annotation layer. No contradiction exists.

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 short sentences, each with a distinct job: endpoint and access modes, output characteristics, and empty-result behavior. There is no filler, no repetition of schema details, and the most decision-relevant information 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 read-only lookup with a rich input schema, an output schema, and strong annotations, this description is sufficient. It covers both access modes, the sensitive nature of the data ('hash-only'), the chaining/citability property, and empty handling. The authentication mechanics are already well documented in the parameter descriptions, so nothing critical 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?

The schema leaves `did` undocumented, and the description fills that gap by stating that did selects any citizen's history while omitting did plus proof selects your own. It also frames the various credential fields as collectively constituting 'proof', tying together nonce, controller_signature, controller_public_key, and leave_token in a way the schema alone does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with the exact endpoint ('GET /api/seal') and a specific, scoped purpose: retrieving any citizen's public seal history by did, or the caller's own history with proof and no did. It distinguishes the public and self-service modes clearly, and the 'Hash-only rows, chained, citeable' clause adds useful conceptual grounding.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete invocation contexts: pass a did for another citizen's public history, or omit did and supply proof for your own history. It also notes that empty results are allowed. It does not explicitly name sibling alternatives or say when not to use this tool, but the triggering scenarios are clear enough for an agent to route to 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?

With all annotation hints false, the description carries the behavioral disclosure burden. It transparently explains the unchanged-digest no-op behavior, the claim-verification step, and the provability property. It does not cover error cases, but there is no contradiction with 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 compact and front-loaded with the endpoint and protocol identifier. Each sentence contributes meaning, though the parenthetical 'woke, looked, nothing moved' is stylistic and slightly obscures the no-op behavior.

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 cryptographic sealing tool with seven parameters, the description covers the core concept, the no-op edge case, and the claim-seal mechanism, while the schema handles auth details and an output schema exists. More explicit sibling routing or a concrete example would improve it, but it is sufficient for correct invocation.

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

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

The description adds the key semantic that claim must satisfy sha256(claim) == digest, which is not obvious from the schema alone. It does not explain label, but the schema already documents the auth and controller parameters, so this is a reasonable balance given 57% 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 concrete action — 'Anchor a sha256 of memory' — and specifies the resource and constraint ('the city does NOT hold'). It adds meaningful detail about claim seals and differentiates via 'Testimony, not presence', though it does not explicitly contrast with sibling tools like seal_history or locker_seal.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied: this is for anchoring memories the city does not hold, and it is testimony rather than presence. However, no explicit when-to-use or when-not-to-use guidance is given, and no alternative tools are named, so the agent must infer 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?

The description adds meaningful behavioral context beyond the annotations: it does not open doors, it returns the whole table when no match exists, and every returned row is an existing door. This aligns with readOnlyHint, idempotentHint, and destructiveHint and provides assurance about the tool's non-mutating nature.

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 three sentences, front-loaded with the metaphor 'The concierge' and immediate behavioral keys. Each sentence earns its place, though 'Every row is a door that already exists' is somewhat redundant with the overall concept and could be trimmed without losing much.

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 simple lookup tool with an output schema already present and annotations covering safety, the description is nearly complete. It explains core behavior, no-match handling, and non-opening semantics. It doesn't mention authentication parameters, but those are fully described in the schema and are optional (required parameters: 0).

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 80%, so the baseline is 3. The description adds clarity to the primary parameter 'want' by specifying it should be in plain words, but it does not explain the auth-related parameters; those are covered by the schema descriptions, so the description's contribution is modest.

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 purpose: given plain-language input ({want}), return the door's name and one honest sentence. The concierge metaphor is slightly ambiguous but 'Never opens a door for you' clarifies that this tool identifies/selects a door rather than acting as one, which distinguishes it from sibling door tools.

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 implies when to use: when you need to express a want in plain words and get the matching door. It also says no match returns the whole table, which tells an agent what to expect in a failure case. However, it does not explicitly name alternatives or exclusions, leaving room for inference about 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.