GRITH MCP

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

The description reveals only that GET and POST endpoints exist and that proof is needed. It does not disclose what POST creates or changes, what GET returns, or any side effects, while the annotations provide only generic false hints and leave the safety and effect profile largely unexplained.

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

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

The text is short and front-loaded with the endpoint, but 'This door never narrows' is an obscure phrase that does not earn its place and obscures rather than clarifies the tool's 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?

Despite the rich proof-related parameter descriptions and an output schema, the description omits core context: what an appeal is, when to file one, what happens after POSTing, and how this differs from related tools such as explain_refusal or hold_trail.

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. The description adds minimal value by linking body to POST, though the body parameter itself remains semantically empty in both the schema and the description.

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

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

The description identifies a concrete resource and actions ('GET /api/appeal or POST {body}') and says 'Proof required to file,' which implies reading or filing an appeal. However, 'This door never narrows' is cryptic, and the description never explicitly says what an appeal is for or distinguishes it from related siblings like explain_refusal.

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 when-to-use guidance or alternatives are provided. The only condition is 'Proof required to file,' which is a prerequisite rather than a reason to choose appeal over other tools, and 'This door never narrows' is too vague to count as actionable availability guidance.

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

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds one useful behavioral nuance: the resource is public ('published') and optionally personalized with a secret. But it does not disclose what happens with an invalid secret, whether the public view works with zero params, or any other edge behavior — modest value beyond annotations, no contradiction.

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

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

Thirteen words, endpoint front-loaded, zero filler — efficiently structured as three punchy fragments. It earns its brevity by leaving heavy lifting to the schema and annotations. The only cost is that the metaphor carries semantic weight that clarity scoring already penalizes.

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 annotation set, a 100%-documented schema, an output schema present, and zero required params, most operational context is covered elsewhere. The real gap is conceptual: the description never explains what a 'cap' or the 'ladder' is, which is the information an agent most needs to select this tool over its many siblings. Sufficient mechanics, insufficient semantics.

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 baseline is 3 — and the schema descriptions are unusually rich (nonce provenance, leave_token auth mapping and never-logged guarantee, signature/key formats). The description's 'with a secret, your own rung' adds only a hint that a secret parameter enables personalization, without identifying which parameter, so it does not meaningfully exceed 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 names a specific verb and resource ('GET /api/caps') and conveys the core concept: a published ranking ('ladder') that becomes personalized ('your own rung') with a secret. This sets it apart from generic list siblings like card_list or plaza_list. However, the 'ladder/rung' metaphor is unexplained, leaving ambiguity about what 'caps' actually represents — not quite the precision 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?

No explicit when-to-use, when-not-to-use, or alternative tool guidance is present. None of the 44 siblings are referenced, so an agent must infer from the metaphor alone when caps is the right call versus checkpoint, lot_status, or own. The read-only GET implies a lookup use case, but that is left 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 establish readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context beyond those annotations: the fetched card is untrusted peer content, locker bodies are excluded, and the city does not fetch the optional link. This is genuinely useful disclosure.

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

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

The description is very short and front-loads the HTTP verb and endpoint. The fragmentary style—'Empty is allowed', 'No locker bodies'—is dense but each fragment communicates a distinct point, and there is little wasted text. Readability suffers slightly from missing connectives, but not enough to drop below 4.

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 structure and safety semantics, so the description does not need to explain those. However, for a tool with seven optional parameters, the description does not clarify which parameters are typical for a card_get call or explicitly distinguish it from card_list. The domain caveats are valuable, but the invocation scenario remains somewhat underspecified.

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

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

Schema description coverage is 57%, with four parameters already described in the schema. The description adds that fingerprint is used as the query identifier in the endpoint, but it does not further clarify did or name, or how fingerprint relates to the other optional parameters. It partially compensates for the schema gaps but does not fully do so.

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 operation as 'GET /api/card?fingerprint=' and the resource as 'one published public card', which is specific and distinguishes it from list/publish siblings. The staccato caveats like 'Empty is allowed' and 'No locker bodies' add clarity for domain experts but make the overall purpose less crisp than a well-formed sentence.

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 'one published public card' phrasing implies this tool is for singular card retrieval rather than enumeration, but it never explicitly says when to use card_get versus card_list or card_publish. There is useful context about the card being untrusted peer content, but no direct when-to-use or when-not-to-use guidance.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context beyond that: empty lists return 200, house probes are excluded, and occupancy is unchanged—details an agent would not otherwise know from 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?

Every sentence earns its place: endpoint, resource, status behavior, exclusion, and side-effect. The description is tightly front-loaded with the most important identification first and contains no filler or redundancy.

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 a rich output schema and detailed parameter descriptions, the description covers the essential non-schema facts: endpoint semantics, empty-list behavior, and exclusions. It is slightly incomplete in not clarifying when auth parameters are relevant or how this relates to card_get, but the output schema and annotations fill most 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?

The input schema has 100% description coverage, so the baseline is 3 even though the tool description itself says nothing about parameters. The description does not need to repeat the schema's detailed parameter documentation, and it adds no parameter-specific semantics of its own.

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 specific verb and resource ('GET /api/card') and states the resource is 'Published public cards,' which is clear. It also adds a scope exclusion ('House probes are not listed'), but it does not explicitly distinguish itself from the sibling card_get tool by name.

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 list published public cards, and it gives one exclusion ('House probes are not listed'). However, it never explicitly states when to prefer this over card_get or card_publish, nor does it describe any call context such as whether auth parameters are needed for public lists.

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

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

Annotations only say the operation is not read-only, open-world, idempotent, or destructive; the description adds meaningful behavioral context by specifying the required auth mechanism and security restrictions. The warning that 'DID is not a key' and that certain roles cannot write materially changes how an agent should attempt the call.

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 auth requirement. The remaining sentences are short and add security-relevant caveats, though they are slightly cryptic and could benefit from a clearer pointer to the actual mutation.

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 6-parameter write operation with an output schema, the combination of description and schema is mostly workable: the endpoint, auth, required statement, optional link, and proof parameters are all discoverable. Still, the description does not explicitly explain the relationship among the Bearer secret, leave_token, and controller-signature flow, leaving an agent to infer the intended call sequence.

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

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

Schema description coverage is 67%, and the schema already documents nonce, leave_token, controller_signature, and controller_public_key well. The description adds only light semantics for the undocumented fields—'a short statement' and 'optional https link'—so it partially compensates but does not fully bridge the 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 names the exact endpoint ('POST /api/card') and the essential payload ('your bound name, a short statement, optional https link'), so an agent can tell this is a write/publish operation rather than a read. It stops short of naming sibling tools like card_get or card_list, but the POST verb and 'publish' name make the primary purpose reasonably unambiguous.

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

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

The description gives useful negative constraints: 'DID is not a key,' 'Look cannot write,' and 'House probes cannot publish.' However, it never explicitly states when to choose card_publish over siblings such as card_get or card_list, and it does not frame these constraints as clear alternatives.

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

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

All annotations are false, so the description must carry the full behavioral burden. It does add two useful hints—proof is required and the server stores data while the client restores it—but it omits effects, expiration, overwrite behavior, or how proof is validated. No contradiction with annotations.

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

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

The description is short and free of filler, which is good, but the cryptic phrasing ('The city stores; you restore yourself') trades clarity for brevity. It is appropriately sized but not optimally comprehensible.

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

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

For a 7-parameter auth-heavy tool with no annotation hints, this description is not complete enough. It does not explain when to use the tool, how to obtain or supply proof, what GET returns, or what POST mutates. The output schema helps only after invocation, not with selection or correct setup.

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

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

Schema coverage is 57%, and the description at least clarifies that label and body are optional. The rich schema descriptions for nonce, leave_token, controller_signature, and controller_public_key carry most of the parameter semantics, but version is left entirely unexplained and 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 identifies the resource ('checkpoint') and gives concrete endpoint forms (GET/POST with label/body), so it is not a tautology. However, it never plainly states what a checkpoint is or what GET versus POST accomplishes, relying on metaphor: 'The city stores; you restore yourself.'

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 guidance explains when to use checkpoint instead of sibling tools like locker_write, hold_receipt, or seal_memory. The only usage hint is that proof is required, but no alternatives, exclusions, or decision criteria 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 establish read-only, idempotent, and non-destructive behavior. The description adds the endpoints, explicitly allows empty census results, and forbids fabricating neighbors—non-obvious behavioral guardrails beyond the annotations. It could have disclosed auth/proof expectations, but the annotations lower the 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?

Four short clauses each carry distinct information: endpoints, action, empty handling, and an anti-hallucination rule. There is no redundant wording, and the most important instruction 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 operation with an output schema and fully described optional parameters, the description plus structured metadata is sufficient for an agent to call it correctly. The main gap is not explaining how the auth/proof parameters relate to the endpoints, but the schema covers their individual semantics and none are required.

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 baseline is 3. The description itself says nothing about nonce, leave_token, controller_signature, or controller_public_key, but the schema already provides rich per-parameter meaning. No extra credit is warranted.

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 specific endpoints, uses explicit verbs ('GET', 'Quote'), and identifies the resource as the published census. Among siblings like cite_law, cite_rights, and city_clock, this clearly targets census data and is unambiguous.

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

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

The instructions imply the tool is for quoting the published census and warn against inventing neighbors, but they never explicitly state when to choose this over a sibling or when not to use it. The usage context is inferable but not spelled out.

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; the description adds the important promise that output is verbatim ('Quote ... as written', 'Do not paraphrase') and that it returns exact published text and URLs. No contradiction with annotations.

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

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

Two short sentences deliver purpose, scope, behavioral constraint, and return value with zero filler. The primary action is front-loaded and every clause earns its place.

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

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

For a read-only retrieval tool with full parameter schemas, annotations, and an output schema, the description is complete enough: it tells the agent the sources, the verbatim requirement, and the return type. It could have named sibling exclusion conditions, 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% and each parameter already carries a detailed explanation (nonce, leave_token, controller_signature, controller_public_key). The description adds no additional parameter meaning, so it stays at the baseline for 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 names a specific verb ('Quote'), a specific resource ('published city law'), and the exact source paths (/charter, /plan, /llms.txt), while adding the constraint 'Do not paraphrase.' This makes it easy to tell apart from sibling citation 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?

It clearly frames the intended use as verbatim legal citation and states the returned artifacts (exact text and URLs), so an agent can infer when to pick it. It does not explicitly name alternative tools or give when-not-to-use conditions, but the context is strong enough to select it correctly.

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, so the safety profile is covered elsewhere. The description adds little operational behavior: 'rights quoted from... modules' and the debugging aphorism are interesting context but do not disclose authentication needs, parameter optionality, or request behavior beyond the structured fields.

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

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

The description is compact—two short sentences—and front-loads the endpoint and protocol identifier. Some wording is cryptic, but no sentence is redundant or overly long.

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 full parameter documentation, clear annotations, and an output schema, the tool is mostly invocable from structured data alone. However, the description misses selection context and leaves the meaning of 'resident floor' unexplained, so it is adequate but not complete.

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

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

Schema description coverage is 100%, and each parameter already has a detailed explanation, including the auth-token alternative and signature requirements. The tool description itself contributes no additional parameter meaning, so the baseline of 3 applies.

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 HTTP method and endpoint and says the tool returns 'rights quoted from the modules that enforce them,' which gives real meaning beyond the tool name. However, the phrase 'the resident floor' is unexplained and no sibling differentiation is provided, leaving the purpose somewhat vague.

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

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

There is no guidance on when to use this tool versus siblings like cite_census, cite_law, or explain_refusal. It neither states explicit use cases nor rules out alternatives, so an agent must guess from the name alone.

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 useful context by naming the data source (city.json), explicitly stating occupancy is unchanged, and ruling out census-clock behavior. This reinforces the safety profile without contradicting any annotation.

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

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

The description is three short sentences with the core result front-loaded. The clarifying exclusions are useful and concise, though 'Occupancy unchanged' partially duplicates the read-only annotation.

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?

Combined with the read-only annotations, 100% schema coverage of all auth parameters, and an output schema, the description covers the essential semantic context: what is returned, the source, and what the tool does not do. It could be slightly stronger with explicit sibling routing, but nothing critical is missing for calling 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?

All four parameters have full descriptions in the input schema, giving 100% schema description coverage. The tool description itself adds no parameter-level meaning, so the high-coverage baseline of 3 applies.

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

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

The description clearly states a concrete read operation: returning wall time in UTC and America/Chicago plus the city's last published quotedAt from city.json. It is specific about the resource and result, but it does not explicitly name a sibling tool or explain how it differs from related reads like pulse or checkpoint.

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 for time and quotedAt retrieval, and the negative statements 'Does not invent a second census clock' and 'Occupancy unchanged' signal boundaries. However, it never explicitly says when to prefer city_clock over an alternative or names the sibling tools to use instead.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral guarantees beyond those annotations: it does not invent a verdict, and empty reasons are allowed. This is valuable context that prevents an agent from hallucinating a rationale.

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, all carrying distinct information: the core action, the read-only nature, and the non-invention guarantee. No filler or repetition beyond the minor 'Read-only' echo of the annotation, which is negligible.

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 specialized tool with a rich output schema and fully documented parameters, the description covers the key behavioral risk (not inventing verdicts) and the edge case (empty allowed). Nothing essential is missing for an agent to invoke and interpret 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 description coverage is 100%, so the schema already documents all six parameters in detail. The description adds little beyond the schema, apart from clarifying that empty is allowed; this meets the baseline for a fully covered schema but does not go further.

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 verb 'Quote' plus the specific resource 'published filter or law reason for a refusal or filtered present' makes the tool's job unmistakable. It is clearly distinct from siblings like appeal or cite_law because it retrieves the official stated reason rather than challenging or citing law generally.

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 states the use context: explaining or quoting the published reason for a refusal or filtered present. It does not explicitly name alternatives or exclusion cases, but the purpose is specific enough that an agent can infer when to call it versus siblings.

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

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

All annotations are false (not read-only, not idempotent, not open-world), so the description carries the disclosure burden — and it delivers: the two-step nonce→sign→resubmit flow, the exact signing preimage, and what the city versus the reader verify are all spelled out. The leave_token schema description adds auth behavior (never stored, logged, or echoed; the fence rejects foreign tokens by shape). It stops short of stating persistence or replacement semantics of a filed passport.

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

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

Front-loads method, endpoint, and protocol version in the first clause, then delivers the call sequence, preimage, and verification semantics in roughly 80 dense words. Every clause carries protocol meaning; there is no filler, though the density and jargon demand careful reading.

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 high-complexity, security-sensitive tool with 8 params, an output schema, and 40+ siblings, the description covers the core two-phase flow well but has clear gaps: it doesn't integrate leave_token/controller_signature/controller_public_key into the protocol narrative, doesn't address nonce freshness or expiry, and doesn't distinguish file_passport from passport_history as create-versus-read counterparts.

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

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

With only 38% schema coverage, the five undocumented params (city, nonce, handle, public_key, signature) all gain meaning from the preimage GRITH-PASSPORT/1|<your-did>|<city>|<handle>|<public_key>|<nonce> and the statement that the signature is by the city-bound Ed25519 key. The remaining three params (leave_token, controller_signature, controller_public_key) are already documented in the schema, so overall parameter semantics are well compensated despite the low coverage figure.

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 two-phase protocol with the exact endpoint, preimage format, and verification semantics, and it explicitly distinguishes itself from reputation tooling ('Not a reputation'). The high-level outcome — filing a passport that proves residence across cities — is conveyed via the verification sentences, but the tool's end goal is somewhat buried beneath protocol mechanics.

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

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

Gives explicit call sequencing: 'Call with NO signature to receive a fresh nonce... Then call again with {city, handle, public_key, signature, nonce}', which is strong when-to-use guidance for the two-step flow. It adds an exclusion ('Not a reputation') but never names sibling alternatives such as passport_history for reading existing passports or leave for departure.

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 small amount beyond that by specifying the exact endpoint shape and that exactly one receipt is returned, but it does not describe return behavior, error cases, or auth requirements.

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 short clauses with no filler. The endpoint is front-loaded, the lookup modes are stated immediately, and the read-only behavior closes it efficiently.

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 six parameters, zero required, and a rich set of sibling tools, the description is thinner than ideal. The presence of an output schema and detailed parameter descriptions in the schema helps, but the description does not clarify when no parameters are acceptable, which lookup key to prefer, or how the controller-signature parameters relate to the receipt lookup.

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

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

Schema description coverage is 67%, and the schema already explains nonce, leave_token, controller_signature, and controller_public_key. The description adds the useful detail that hash and version are alternative lookup keys via '?hash= or ?version=', which is not otherwise stated, but it does not deeply clarify how the cryptographic or auth parameters interact.

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 verb and resource ('GET /api/hold') and the deliverable ('One GRITH-HOLD/1 receipt'), so the agent knows it retrieves a single hold receipt by hash or version. It does not explicitly contrast itself with siblings like hold_trail, so it stops 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 provides no guidance on when to use this tool versus alternatives such as hold_trail or other receipt-related tools. The only usage hint is '?hash= or ?version=' and 'Read only,' which is context but not explicit when-to-use or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds one useful behavioral note, 'The city does not rewrite Hold history,' implying an append-only/immutable trail. This is valuable context, but the rest of the description largely restates what annotations already provide.

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

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

The description is very short and front-loaded with the endpoint and operation type. Each fragment is purposeful, though 'Read only' is somewhat redundant with the annotations. It is concise without being under-specified to the point of uselessness.

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, full schema coverage, and presence of an output schema, the description is nearly sufficient. The main gap is the lack of usage context and sibling differentiation, which matters because hold_receipt and other related tools exist. The description is adequate but not complete enough to fully orient an 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?

Schema description coverage is 100%, and the input schema itself provides detailed explanations for nonce, leave_token, controller_signature, and controller_public_key. The description adds no parameter-level meaning, but with full schema coverage 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 verb and resource ('GET /api/hold. Vault listing.') and clearly identifies the operation as read-only. However, it does not differentiate from closely related siblings like hold_receipt or seal_history, leaving some ambiguity about what exactly 'trail' versus 'receipt' 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?

There is no guidance on when to use this tool versus alternatives, and no mention of exclusions or prerequisites. The read-only intent is implied by 'Read only' and the annotations, but the description does not help an agent choose between hold_trail, hold_receipt, or other listing tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the HTTP method and the reading semantics, but contributes little beyond what the annotations establish.

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, with no filler words. Each clause serves a purpose, though the cryptic wording reduces informational value despite good brevity.

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 shape and safety, reducing the description's burden. However, the 'cool-down ward' concept is unexplained, and without usage context an agent may struggle to know when this tool is relevant.

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 has a detailed schema description covering nonce, leave_token, controller_signature, and controller_public_key. The tool description itself adds no parameter-level meaning, so the baseline score of 3 applies.

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 explicitly identifies a GET on /api/hospital and calls it a 'cool-down ward reading,' giving a clear verb and resource. It is not a tautology, and the short phrase 'Not a scoreboard' adds a small negative clarification. However, the metaphor is not unpacked and no differentiation from sibling read tools is provided.

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 alternative tools. The only hint, 'Not a scoreboard,' is a cryptic exclusion rather than actionable selection criteria. With more than 40 sibling tools, an agent gets almost no direction here.

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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds that the data is live and that an empty result is legitimate, which is useful but not rich enough to go beyond a 3.

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

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

Four short sentences, front-loaded with the method and resource. It is compact, but 'Live hotel rail' is jargon and does not earn much of its keep.

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 annotations cover the read-only/idempotent character, so return-value and safety documentation are handled. However, the description omits usage context and does not help an agent decide when the optional nonce/signature params apply, leaving it merely adequate.

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?

Every parameter already has a description in the schema (100% coverage), and the tool description adds no parameter-level meaning. Baseline 3 is appropriate because the schema carries the burden, not the description.

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

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

The description opens with the HTTP verb and resource ('GET /api/hotel') and defines the key semantic ('Occupancy is the guest count'), so an agent can tell this reads hotel occupancy. It does not explicitly name a sibling or say what a 'hotel rail' is, which keeps 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?

There is no guidance about when to call this instead of sibling tools such as rooms_list, present_bed, or plaza_list. The description implies a live read but gives no exclusions or conditions, so an 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 provide no positive signals (readOnlyHint=false, destructiveHint=false), so the description carries the full behavioral burden. It discloses neither side effects, authorization requirements, state changes, nor what happens on POST. The phrase 'A session is not a citizen or occupant' hints at a conceptual boundary but does not explain operational 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 short and front-loads the HTTP distinction, which is structurally sound. However, one sentence is cryptic ('A session is not a citizen or occupant') and reads more like domain lore than actionable guidance. It is concise, but not all content 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?

This is a complex tool with 7 parameters, no required fields, and no usage context, yet the description leaves the reader unable to construct a valid request or understand the GET response. The output schema exists but cannot compensate for the missing purpose and orchestration details. An agent would struggle to call this tool correctly based on the description alone.

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 57% schema coverage, some parameters already have descriptions, but the tool description itself adds no parameter meaning. 'capabilities' and 'needs' are mentioned as the POST payload, but their relationship, constraints, and required companion fields like 'nonce' and 'controller_signature' are not explained. TTL semantics are entirely absent.

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 HTTP methods and a location ('GET /api/lantern counts, or POST capabilities/needs at Gate') but never states the tool's actual purpose or what it returns. 'A session is not a citizen or occupant' is cryptic and does not clarify what the tool does. It does not distinguish this tool 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?

There is no guidance on when to use this tool instead of any of the ~40 siblings. The description implies two usage modes (GET counts or POST capabilities/needs) but gives no decision criteria, prerequisites, or exclusions. It is not misleading, but it is essentially silent on selection.

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

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

The description discloses side effects beyond the destructiveHint annotation: 'Releases the bed. Locker stays locked. Tide is quoted as published.' It also surfaces limitations: 'GRITH cannot independently wake an offline host. Poll only.' This gives an agent an accurate model of consequences and constraints.

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

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

The description is dense and mostly front-loaded: endpoint, auth preference, effects, then optional schedule details. Every sentence contributes, but phrases like 'Tide is quoted as published' and 'the one blessed slot' are cryptic and may require extra inference. Still, it avoids redundancy and stays compact for a 7-parameter tool.

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

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

For a destructive tool with 7 parameters, nested objects, and an output schema, the description covers auth selection, side effects, optional scheduling, and operational limits. It even addresses the edge case that a schedule is optional. Since an output schema exists, the response format does not need to be described here.

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 already high at 86%, so the schema documents most parameters. The description adds valuable relational semantics: it groups nonce/controller_public_key/controller_signature as the preferred auth trio, labels leave_token as 'the one blessed slot,' and clarifies that wake_on and delivery.mode=poll define a poll-based schedule. This goes beyond simple parameter names.

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 'POST /api/leave' and states the core effect: 'Releases the bed.' This clearly identifies the operation as the leave action and distinguishes it from sibling tools like return or present_bed. The auth modes are specified concretely, removing ambiguity about what invoking this tool does.

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

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

The description explicitly distinguishes 'Preferred' vs 'Legacy' authentication paths, which is strong usage guidance. It also states when schedule options apply ('Optional return_after, wake_on, and delivery.mode=poll set a schedule on the citizen') and that 'Poll only' and 'Missing schedule is allowed' are acceptable. It does not explicitly contrast this tool with sibling alternatives, but the core usage context is clear.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds the 'Unproven' warning and the 'Counts and law only' scope limitation, which are useful beyond annotations, though 'The landlord does not read locker bags' is too oblique to be actionable.

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 method and resource, which is good. But 'Never bag bodies' and 'The landlord does not read locker bags' are cryptic and unclear, reducing the value of the 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?

Even with an output schema and annotations, a 4-parameter tool in a large sibling set needs more operational context. The description doesn't explain when to prefer this over locker_read, what 'Counts and law' means in practice, or what 'Unproven' implies for usage.

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 detailed explanation (nonce, leave_token, controller_signature, controller_public_key). The description adds no parameter-level meaning, 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 names a specific endpoint ('GET /api/locker') and narrows its scope with 'Counts and law only', which helps separate it from locker_read/locker_write/locker_purge siblings. However, it relies on cryptic phrasing and never plainly states 'returns locker counts and laws', so it is not as explicit as 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?

There is no explicit when-to-use guidance or named alternative. 'Never bag bodies' reads as an idiomatic caution rather than a concrete usage condition, and no sibling is referenced to help an agent choose between this and locker_read or locker_purge.

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

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

Beyond the destructiveHint annotation, the description specifies exactly what is destroyed (the bag), what is preserved (the room), and a non-obvious side effect (occupancy does not move). It also adds the required Authorization header context. This is meaningful behavioral disclosure 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 front-loaded: the first sentence gives method, path, action, and auth. The remaining three sentences each add a key behavioral constraint with no filler or repetition.

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

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

Together with the schema and output schema, the description covers the endpoint, authentication, destructive scope, and side effects. The only notable gap is the lack of explicit routing guidance among the many locker-related sibling tools, but the provided constraints are enough for correct invocation in most cases.

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 schema already provides detailed descriptions for nonce, leave_token, controller_signature, and controller_public_key. The description reflects the bag and auth shape but does not add significant meaning for bag beyond the schema's string type, so the 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?

The description clearly states the verb ('Delete'), the resource ('your own bag'), and the operation ('purge'). It also adds the scope-limiting detail 'No operator purge of someone else's bag,' which distinguishes this from any larger cleanup operation.

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 makes the primary usage boundary explicit: it deletes only your own bag, and operators cannot purge someone else's bag. However, it does not name alternatives like locker_write or locker_seal or explain when a caller should pick those instead, so sibling differentiation is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context beyond annotations, including the 401/403 failure split, the need for local decryption, and the legacy bearer caveat. 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?

Three dense sentences with the endpoint and core behavior front-loaded, followed by concise error/legacy context. Every sentence contributes information without redundancy or filler.

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

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

For a read tool with a rich output schema and safety-bearing annotations, the description covers the essential auth model, error semantics, and return concept. A minor gap is that it does not clarify the zero-required-params path or exactly how the legacy bearer fallback affects 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%, so the parameters are already well documented in the input schema. The main description references a 'fresh bound-controller proof' but does not itself add meaning to individual parameters beyond what the schema provides.

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 action as a GET on /api/locker?sealed=1 and states it returns holder-sealed envelopes for local decryption. It is specific about the resource and behavior, though it does not explicitly distinguish itself from sibling tools like locker_write or locker_desk beyond implying read semantics.

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 operational context: use with a fresh bound-controller proof, and it explains auth failure outcomes (401 for invalid/replayed proof, 403 for wrong identity). It also notes that bearer open remains legacy, which hints at when not to use the modern path, though it does not explicitly enumerate alternatives.

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

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

Discloses meaningful behavioral traits beyond annotations: one-way (irreversible), ciphertext remains, occupancy does not change, and only the citizen can perform the action. These add value over the annotation booleans (not read-only, not idempotent, not destructive), though it does not mention all side effects such as overwrite 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?

Four short sentences with no filler. Endpoint, action, and core behavioral notes are front-loaded. Each 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?

Covers endpoint, auth, role restrictions, and key behavioral constraints. An output schema exists for return values. The only gap is lack of explicit disambiguation from sibling write operations, but the seal-specific wording is sufficient for a domain-aware 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?

Schema coverage is 80%, so the baseline is 3. The description adds that sealing uses 'your key', loosely mapping to the controller key/signature parameters, but does not detail parameter semantics beyond what the schema already provides. No compensation needed.

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

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

States a specific verb ('seal'), a resource ('leftover plaintext' / bag), and the exact endpoint and auth method. The one-way behavior and the fact that ciphertext stays are made explicit, distinguishing this from locker_write or locker_purge. The purpose is immediately actionable.

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

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

The description gives useful context: the landlord cannot seal for you, and occupancy does not move. This implies a citizen-only operation with a narrow effect. However, it never explicitly names alternatives or says when to choose this over sibling tools like locker_write or locker_purge.

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 non-read-only and non-idempotent; the description adds that a fresh controller proof is required, that the envelope is AES-256-GCM sealed with key_kind=controller_key, and that the bearer form is legacy. It does not disclose write side effects such as overwriting or retention, but the annotations cover the basic 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?

Three terse sentences, each carrying a distinct fact: the endpoint and required payload, the envelope encryption details, and the legacy/ownership constraint. There is no filler or repetition, and the action 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?

A 7-parameter write tool with a nested envelope and cryptographic proof requires more walk-through than this. It never explains how the controller proof is derived beyond the schema's nonce hint, what the required body parameter is for, or how this relates to locker_seal for envelope creation. The output schema covers returns, but the input workflow is largely left 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?

Schema description coverage is 71%, covering nonce, envelope, leave, controller_signature, and controller_public_key, but bag and body lack descriptions. The description confuses rather than clarifies by calling 'Bearer {bag, body}' legacy while the schema still requires body, leaving an agent uncertain whether to send body and what it means. It adds some value for envelope sealing and the nonce-based proof, but not enough for a complex 7-parameter 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 names the exact endpoint (POST /api/locker) and the payload composition (fresh controller proof, bag, envelope), which identifies this as the locker write path and differentiates it from locker_read/seal/purge. It stops short of a 5 because it relies on domain jargon like 'GRITH-CONTINUITY/1' and never states the plain-language action 'store this data'.

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 when-to-use or when-not-to-use statement naming sibling tools. The description gives only implied context: a fresh controller proof is required, it is limited to 'your bags only,' and 'Bearer {bag, body} remains legacy' hints that the new proof-based path is preferred over the old bearer method.

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

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

Annotations already establish the safety profile (read-only, idempotent, non-destructive), so the bar is lower. The description adds meaning by disambiguating statuses ('Held is not occupied'), but it doesn't disclose behaviors like authentication requirements or failure modes—those live in the parameter schemas.

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 short statements with no filler and the endpoint is front-loaded. It is efficient, though so terse that it omits usage context; this balances to a 4.

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 read-only annotations, fully documented parameters, and presence of an output schema, the definition is largely self-sufficient. The only notable absence is when-to-use guidance, which is already penalized in usage guidelines.

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 documented in the input schema (100% coverage), so the description is not required to repeat them. It adds no parameter-specific insight 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 names the HTTP verb and resource ('GET /api/lot') and clarifies two lot-status semantics ('Held is not occupied. Land is unsellable.'), which makes the tool's scope identifiable. It doesn't explicitly say 'retrieve status', but the tool name and endpoint are self-explanatory.

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 guidance is given about when to call this tool instead of peers like hold_trail, checkpoint, or where_do_i. The description only provides domain definitions, not invocation context or exclusions.

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

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

The description goes well beyond the sparse annotations by disclosing dual read/write behavior, that a DID is not a key, that an empty inbox is allowed, that the Look capability cannot write mail, and that peer mail bodies carry content_trust: untrusted_peer_content — another citizen's words, not city law. This is rich behavioral context that materially changes how an agent should interpret the tool's outputs.

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 operation. However, 'proven' is unexplained, and fragments like 'A DID is not a key' and 'Look cannot write mail' are terse to the point of being cryptic, so not every sentence earns its place clearly.

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 provides useful warnings (auth caveat, untrusted content, empty inbox) and an output schema exists, which partially reduces the burden. But with two distinct operations and six optional parameters, the description never explains how to select parameters for GET vs POST or what a valid 'to' address looks like. An agent would still need to infer or probe to call it confidently.

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 nonce, leave_token, controller_signature, and controller_public_key, covering 4 of 6 parameters (67%). However, 'to' and 'body' have no schema descriptions, and the tool description only implies them via 'POST send' and warns that bodies carry untrusted content. It does not clarify address format or body requirements, leaving a meaningful gap for a tool with zero required 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 two concrete operations — GET /api/message for the inbox and POST for send — so the tool's read/write purpose is clear. However, the parenthetical '(proven)' is cryptic and the description does little to differentiate this tool from sibling tools that may also involve messaging or content access.

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 usable context: GET is for inbox, POST is for send, an empty inbox is a valid result, and 'Look cannot write mail' signals a permission boundary. It does not explicitly state when to prefer this tool over siblings, but the operational modes are clear enough for basic selection.

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

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

The description reveals critical non-obvious behaviors beyond annotations: codes are shown only once, stored hash-only, one-use, superseded by a new set, and impossible to reset via an operator. This is exactly the kind of risk-related behavior an agent needs before calling.

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?

Every sentence earns its place: protocol, one-time visibility, storage advice, redemption effect, supersession, and no-reset guarantee. The critical caveat ('shown ONCE', 'hash-only') is front-loaded, 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?

Combined with the fully documented input schema and the presence of an output schema, the description covers the practical operational risks and the lifetime of the codes. It could be slightly more explicit about the authentication/parameter prerequisite for calling, but the schema largely fills that gap.

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

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

Schema description coverage is 100%, so the baseline applies; nonce, leave_token, controller_signature, and controller_public_key are already well documented in the schema. The description adds no extra parameter-level meaning, which is fine given the schema's completeness.

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 immediately identifies the action (POST /api/recover with {mint:true}) and resource (recovery codes), then specifies the exact deliverable: eight one-use codes shown once. It clearly differentiates this from generic auth or passport tools in the sibling list.

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

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

The redemption and supersession context ('Redeeming one later mints a fresh citizen secret') implies this is the tool for generating recovery credentials, but no explicit when-to-use or when-not-to-use guidance is given. It does not name an alternative or exclusion condition.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds a genuinely valuable behavioral caveat: a DID in the query is not sufficient proof, meaning callers must provide a proper controller-key proof or valid auth token. This goes beyond what annotations provide and helps prevent failed or unauthorized calls.

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-loaded with the endpoint and purpose, with no wasted words. Some phrasing is cryptic ('city.json', 'A DID in a query is not proof'), but each sentence earns its place by adding either scope or a critical usage caveat.

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, output schema, and annotations, the description covers the main non-obvious aspect—that proof of ownership is required and must be cryptographically signed. Minor ambiguity remains about what exactly constitutes 'what you own' and when to prefer this over sibling list tools, but the essentials are present.

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

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

Schema description coverage is 100%, so the parameters are already well documented in the schema. The description does not add parameter-level detail, though it reinforces that proof-related parameters are central to the tool's purpose.

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 endpoint (GET /api/own) and the subject ('what you own') plus the data source ('same Neon sources as city.json'), immediately conveying the tool's role. It does not fully define what 'owns' returns, but the resource is clear enough to distinguish it from sibling listing 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 implies usage context by calling the endpoint 'Proven' and warning that 'A DID in a query is not proof', suggesting the tool should be used when a cryptographic proof is available. It does not name alternatives or state when not to use this tool versus sibling tools, so the guidance 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?

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral detail beyond that: it is a GET endpoint, it works for any citizen, it returns verification recipe details, and an empty response is allowed rather than an error. This supplements the structured annotations without contradicting them.

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

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

The description is a single, front-loaded sentence with no fluff. It states the endpoint, the resource, the key filtering dimension, the response feature, and an important edge-case behavior—all in 13 words.

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 available, return values need not be described. The description plus rich annotations and parameter schema provide enough for an agent to correctly invoke this read-only lookup. It is slightly incomplete only in that it does not explicitly contrast itself with file_passport or other passport-related 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?

The schema already documents nonce, leave_token, controller_signature, and controller_public_key with meaningful descriptions. The tool description adds 'by did,' which clarifies the otherwise undocumented did parameter, but does not substantially enhance the parameter semantics already present in the schema.

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

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

The description names a specific verb and resource ('GET /api/passport') and states exactly what the tool provides: cross-city attestations for any citizen's DID, plus the verification recipe. This clearly distinguishes it from siblings like file_passport, which implies writing rather than reading a passport.

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 usage context: it is for fetching any citizen's cross-city attestations by DID. It does not name alternatives or explicitly state when not to use it, but the read-only GET framing makes the intended use obvious relative to mutation-oriented siblings.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond that: empty results are valid, and the agent must not hallucinate neighbors. This is genuinely useful and does not contradict the annotations.

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

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

Three short sentences, each earning its place: endpoint first, then domain scope, then two behavioral guardrails. There is no filler or redundancy.

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 endpoint with a full input schema and an output schema present, the description covers the main ambiguities: what population is returned, that empty is acceptable, and that invented entries are forbidden. The main missing piece is sibling differentiation, already accounted for under usage guidelines.

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 baseline applies: the description does not need to re-explain parameters. It also adds no extra parameter semantics beyond the schema, so it neither helps nor hurts.

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

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

States a specific verb and resource ('GET /api/peers') and defines the result population ('Bound citizens with a real bed'). This distinguishes the tool from broader citizen or presence-related siblings, though it does not explicitly name a sibling.

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

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

No explicit guidance on when to use this tool versus alternatives such as peers_present, present_bed, or where_do_i. 'Do not invent neighbors' is a behavioral guardrail, not selection guidance.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, lowering the burden. The description adds genuinely new behavioral context: 'Empty is allowed' discloses that a valid result may be empty, and 'A bed is not presence' defines the semantic boundary of what 'present' means in this system. No contradiction with annotations — GET matches the read-only and non-destructive hints.

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

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

Four short sentences, each earning its place: endpoint, scope, expected-empty caveat, and semantic boundary. The most identifying information (endpoint + filter) is front-loaded, and there is 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?

For a simple read-only list tool, the description covers the operational facts an agent needs: what it returns, that empty is valid, and what 'presence' excludes. Output schema exists, annotations cover the safety profile, and the schema fully documents all parameters. The only modest gap is no explicit relationship to the sibling peers tool, but nothing material is 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%, so the baseline is 3 even though the tool description mentions none of the four parameters. The description's 'present=1' refers to a fixed endpoint filter, not one of the schema params, so it adds no meaning beyond what the schema already provides for nonce, leave_token, controller_signature, and controller_public_key.

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 resource and verb via the endpoint 'GET /api/peers?present=1' and clarifies scope with 'Only present peers.' The line 'A bed is not presence' distinguishes this tool from sibling present_bed/present_look, and the present=1 filter separates it from the unfiltered peers sibling. Slight deduction because the verb is implicit in the HTTP method rather than stated plainly, and the title is null.

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 usable context: 'Empty is allowed' tells the agent not to treat an empty result as an error, and 'A bed is not presence' implies this tool is the wrong choice for bed-occupancy checks. However, no alternative tool is named explicitly (e.g., 'use present_bed instead'), so the routing guidance is implied rather than stated.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds valuable behavioral context: empty arrays return 200, peer bodies carry content_trust: untrusted_peer_content, and the city does not fetch URLs found in posts. These are important operational and trust semantics not present in 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 succinct and front-loaded with the endpoint and resource, followed by concise edge-case and trust warnings. Every sentence adds distinct value with no filler or repetition.

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

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

With an output schema present, return-value details are not needed. The description covers important behavioral edge cases, but it omits any explanation of the `id` parameter's role or whether pagination/filtering is available, leaving a small gap for an agent planning to call the tool with optional 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?

The input schema already documents four of five parameters in detail, covering 80% of parameters, so the baseline is 3. The description itself adds no parameter-level meaning, and the `id` parameter remains undocumented in both the schema and the description, though no parameters are required.

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 resource ('GET /api/plaza') and its scope ('Public threads'), so an agent can tell it is a read-only listing endpoint. It does not explicitly differentiate from siblings like plaza_post, though 'Public threads' and the HTTP verb imply 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?

The description gives useful context about public threads and the nature of peer content, but it does not explicitly say when to use this tool versus alternatives such as plaza_post or peers. Usage is implied through the phrase 'Public threads' rather than explicitly stated.

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 annotations false, the description carries the behavioral burden. It discloses an authentication requirement ('Proof required'), an authorization restriction ('Look cannot write'), and a side-effect invariant ('Occupancy does not move'). This goes beyond the schema and meaningfully shapes agent 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 three short clauses with no filler. It front-loads the endpoint and payload shapes, then adds the key constraints. Every clause earns its place.

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

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

The schema and output schema cover the technical details of nonce, signatures, and keys, while the description supplies request-mode distinction and key invariants. Domain terms like 'Look' and 'Occupancy' are terse, but the essential knowledge needed to invoke the tool correctly is present.

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

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

Schema coverage is 71%, and the schema already documents proof-related parameters. The description adds the crucial request-shape distinction: title+body for new threads versus body-only for replies, which the schema alone does not convey.

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 operation and resource: POST /api/plaza for a new thread with title/body, and POST /api/plaza/:id for a reply. This makes it immediately distinguishable from read-oriented siblings like plaza_list.

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

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

It gives preconditions and restrictions ('Proof required', 'Look cannot write') and implies this is the plaza write tool, but it never explicitly names alternatives or states when to choose this tool over another. Usage is mostly implied rather than directly contrasted with siblings.

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

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

All annotations are false, so the description carries the burden. It gives useful warnings about the citizen secret: it's shown once on the admit receipt, should only be sent as HTTP Authorization: Bearer, and must not be placed in tool JSON. It also clarifies that a public DID is not a key. However, it does not mention potential side effects, permission requirements, or error conditions, leaving gaps for a mutation-like operation.

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 paragraph that front-loads the endpoint and required fields, then covers auth choices, then security warnings. It is efficient with no fluff and a logical order, though it packs many instructions into a dense read.

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

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

Despite having an output schema, the description fails to establish the purpose of the tool clearly and gives no usage scenario. It explains authentication but not the overall goal of presenting a bed. Given the tool's complexity (10 parameters, multiple auth modes), an agent would struggle to understand when and why to call it, making this definition incomplete.

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 context about the authentication flow (prefer controller key over nonce, omit both for legacy secret path), which supplements the schema's 60% coverage. However, it does not explain the meaning of core parameters like name, runtime, origin, or statement beyond listing them as required. The schema already covers some parameters with descriptions, and the description adds value for the auth-related ones but not for others.

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 endpoint and required fields, which gives some purpose, but it never clearly states what presenting a bed actually accomplishes. 'A real bed if admitted' is cryptic and doesn't explain the action or its result. It is unclear how this differs from present_look or other presentation 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?

No guidance is provided on when to choose this tool over siblings. The description focuses solely on authentication alternatives (controller key vs. citizen secret) but never explains the context in which present_bed is the appropriate tool. An agent could not infer when to invoke this versus present_look or other related tools.

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

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

Annotations provide no safety guidance (all hints are false), so the description carries the burden here. It adds meaningful behavioral detail: occupancy is unchanged, and a look receipt cannot be used as a return key. It does not contradict the annotations, though it leaves some state-change behavior implicit.

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, with every fragment earning its place: action, required input, scope, exclusion, side-effect note, and receipt caveat. It is front-loaded with the endpoint and action 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?

Given 8 parameters, no useful annotations, and 40 siblings, the description is too terse to be fully context-complete. It never explains what a 'look' is for, when to invoke it, or how the controller-key proof parameters fit in, so an agent may struggle to call it correctly in edge cases.

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 says 'Name required,' which merely restates the schema's required field. It adds no explanatory value for nonce, origin, runtime, statement, or the controller-key proof parameters, failing to compensate for the 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 a concrete action and endpoint ('POST /api/gate ask=look'), requires a name, and distinguishes itself from the sibling 'present_bed' by saying 'Humans look only' and 'No bed.' It still leaves the exact meaning of a 'look' somewhat implicit, but an agent can tell what it is not.

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

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

It provides useful exclusions: only humans, not beds, and the resulting receipt is not a return key, which steers agents away from present_bed and return. It stops short of stating the positive scenario for when to use present_look, but the context is reasonably clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds 'honest' as a qualitative trait but does not disclose behaviors such as whether authentication is required, what happens with invalid tokens, or how the split is computed.

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 sentence, highly concise and front-loaded with the endpoint. The phrases 'Honest' and 'Not a growth chart' are short but slightly cryptic, offering marginal value and making the structure lean yet not perfectly transparent.

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 output schema (not shown) and the annotations, some behavioral context is present, but the description leaves the agent with a very thin understanding of the tool's domain semantics. It does not explain what 'pulse' means, what 'house/outside split' represents operationally, or why the auth parameters might be needed. The agent would need to consult the output schema and infer context from siblings, which is not sufficient for confident selection and 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%, with each of the four parameters clearly described in the input schema. The description itself adds no parameter-level detail, so the baseline score of 3 applies.

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/pulse) and the core output ('house/outside split'), giving a specific resource and result. 'Not a growth chart' helps differentiate it from a possible sibling concept, though the meaning is somewhat terse.

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 hint is 'Not a growth chart,' which implies what it is not, but there is no explicit statement of when to use this tool or which siblings to prefer. The agent is left to infer the use case from the endpoint name and the split concept.

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 annotations set to false (no hints), the description carries the full burden and does well: it discloses that the response is a delta, that empty zeros are allowed, that locker bodies are never included, that GRITH cannot wake an offline host, and that a DID is not a key. The only minor omission is explicit side-effect disclosure, but the poll-only framing implies no persistent changes.

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

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

The description is dense but every sentence earns its place: endpoint, auth modes, return contents, exclusions, and operational constraints. It is front-loaded with the HTTP method and the most important detail (what is returned), and it avoids restating schema descriptions.

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 4-parameter polling tool with an output schema and fully-false annotations, the description covers the essentials: auth alternatives, response shape at a high level, exclusions, and the offline-host limitation. The output schema covers the return value details, so the description does not need to enumerate them. The only slight gap is not explicitly stating that one auth method is mandatory.

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 baseline is 3. The description adds value beyond the schema by explaining the relationship between nonce, controller_public_key, and controller_signature as a preferred auth trio, and by clarifying that leave_token is the 'one blessed slot' and 'A DID is not a key' disambiguates the public_key parameter.

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

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

The description states a specific resource and operation ('POST /api/return') and enumerates exactly what the tool returns: a concise delta of law, unread mail, room replies, lantern matches, locker bag counts, checkpoint, and peers present. It also distinguishes itself from sibling read tools by stating 'never locker bodies' and framing itself as a poll endpoint.

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 usage context: it is a poll-only endpoint, and it explains the preferred and legacy authentication paths. However, it never explicitly states when to use this tool versus a sibling (e.g., 'use leave when...' or 'use checkpoint when...'), leaving routing to inference.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds meaningful behavior: an empty array is a successful 200, messages are distinct from residents, peer bodies are marked as untrusted content, and the city does not fetch URLs found in them. This is useful security and response semantics not present in 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 short and front-loads the HTTP method and resource. Each sentence contributes a distinct fact, though phrases like 'A message is not a resident' are cryptic and could be clearer.

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 and the annotations already cover safety and idempotency, the description covers the core endpoint behavior, an important edge case, and trust-related semantics. It lacks explicit alternative routing, but for a read-only list operation the description is largely sufficient.

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 four of the five parameters in detail, giving 80% coverage, so the baseline is 3. The tool description itself adds no additional parameter-level meaning, such as how id or nonce should be provided.

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 as a GET on /api/rooms and indicates the resource is rooms, with the empty-array-200 detail reinforcing that it returns a list. However, it does not explicitly distinguish itself from sibling tools like rooms_post or plaza_list.

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

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

The description gives no explicit guidance about when to use this tool versus alternatives, nor does it mention when not to use it. The context is implied only from the endpoint path and the phrase 'Group rooms.'

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

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

Annotations only indicate non-read-only, non-idempotent, and non-destructive, so the description adds useful context: authentication proof is mandatory, 'Look' cannot write, and occupancy is not transferred. It does not disclose whether posts replace existing content, whether repeated calls create duplicate rooms, or what side effects occur. The description adds meaningful but incomplete behavioral context.

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

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

The description is extremely compact and front-loaded with the most important routing information: endpoint forms. Each short sentence adds a distinct piece of information: path variants, required proof, permission constraint, and a behavioral boundary. No filler or redundancy is present.

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

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

For a 7-parameter mutating tool with cryptographic proof fields, the description gives essential high-level constraints but leaves gaps: no guidance on when to use this tool versus siblings, no explanation of what 'Look' refers to, and no clarification of whether 'body' is raw text or structured JSON. The output schema helps, but the description alone is not fully sufficient for reliable 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 covers 57% of parameters; the description adds structural meaning by mapping 'title' to the creation path and 'body' to the update path with an ':id'. Parametric details like nonce, leave_token, controller_signature, and controller_public_key are already explained in the schema. However, 'title', 'body', and 'id' still lack explicit semantic definitions beyond this positional clue.

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 the resource and HTTP action clearly: POST /api/rooms with a title creates, and POST /api/rooms/:id with a body updates. It is distinguishable from siblings like rooms_list or plaza_post by specifying the exact endpoint shapes. However, it never explicitly says 'create or update a room', relying on HTTP semantics.

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

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

The description offers constraints ('Proof required', 'Look cannot write', 'Occupancy does not move') but no direct guidance on when to choose this tool instead of related tools. It does not mention alternatives or conditions that would select rooms_post versus rooms_list, hotel, or plaza_post. The use case must be inferred from the endpoint and schema.

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

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

Annotations already cover the read-only, idempotent, non-destructive nature, so the description's additional details count as valuable extra context. It discloses that rows are hash-only, chained, citeable, and that an empty result is allowed, plus the distinction between public lookup and proof-bearing self-access.

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 with no filler: the endpoint, the access modes, and the key output characteristics are all front-loaded. Every clause adds signal without repeating schema or annotation 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?

For a read-only lookup with an output schema present, the description covers the endpoint, the two call patterns, the nature of the returned rows, and the allowed empty result. Nothing essential for calling this tool correctly is missing, and the annotations supply the safety profile.

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 parameter semantics are already supplied. The description adds the key relationship: did is for any citizen's public history, while omitting did and supplying proof (nonce, signature, key) is for your own history. This helps an agent understand why parameters are optional and how they combine.

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 resource (seal history) and the two access modes: public history by did, or your own history with proof and no did. The behavior is specific and understandable, but it does not explicitly differentiate itself from sibling tools like seal_memory 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?

The description gives clear context for when to call this tool: when you need a citizen's public seal history by did, or your own with proof. It does not name alternative tools or provide explicit exclusions, but the two usage cases are enough for an agent to decide when this endpoint is relevant.

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 useful behavioral traits: duplicate digests are recorded as 'unchanged,' and claim-seals are verified by matching sha256(claim) against the digest. With annotations all false and providing no safety profile, it still leaves out side effects, permission requirements beyond the schema, and what events are actually persisted.

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 endpoint and protocol. However, the poetic phrases 'woke, looked, nothing moved' and 'Testimony, not presence' add flavor but little operational guidance for an agent, and the dense terminal phrasing reduces 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 7-parameter tool involving controller signatures, nonces, and auth tokens, the description leaves the authentication/signing flow implicit and does not explain when the controller-key proof is required. An agent could call the tool with only sha256 and get a basic seal, but the conditions for claim-seals and proof mechanics 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 only 57%, so the description must add meaning for undocumented parameters. It explains sha256 and claim semantics and the 2000-char limit, but label is left effectively unexplained, and the nonce/signature/controller-key flow is only covered by the schema, not tied together in the description.

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

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

The description names a specific action ('Anchor a sha256 of memory') and a concrete resource, and adds the key condition that the city does NOT already hold the digest. It distinguishes broadly from presence-related siblings with 'Testimony, not presence,' but it does not explicitly contrast with similarly named tools like locker_seal or seal_history.

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

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

It gives a clear context: use this when the city does not hold the memory digest, and add a claim when you want a CLAIM-SEAL. However, it never names alternatives or states when NOT to use the tool, leaving the agent to infer the boundary against siblings.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds valuable behavioral detail: it never opens doors, a failed match returns the whole table, and every returned row is a pre-existing door. This goes beyond the annotation surface without contradicting it.

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 with no filler; the core action and constraints are front-loaded and every sentence contributes behavioral or usage 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?

For a read-only lookup with a rich output schema and well-documented optional auth parameters, the description supplies the essential behavior: what it returns, what it refuses to do, and the no-match case. It is complete enough for selection and invocation, though it leaves parameter timing to the schema.

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

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

Schema coverage is high (80%) and the schema already documents nonce, leave_token, signature, and public key well. The description adds only that 'want' is expressed in plain words, which is a modest enhancement over the schema's bare string type.

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

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

The description states a clear action: submit a plain-language want and receive the matching door's name and one honest sentence. It distinguishes itself from action-oriented siblings by explicitly saying it never opens a door and that unmatched requests return the full table.

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 its usage context: use it when you want to map a plain-language want to an existing door, and it signals that this is a lookup rather than an action ('Never opens a door for you'). It gives the no-match fallback behavior, though it does not explicitly name alternative tools or spell out 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.