scry — agent conduct meter, vow oracle, and the agent town

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

Annotations already provide readOnlyHint=true and idempotentHint=true, covering safety. The description adds behavioral context about the content (explaining scry, free vs paid, honest-scope card) but does not disclose any additional behavioral traits beyond what annotations provide. This adds some value but is not rich.

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

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

The description is two sentences with no wasted words. It is front-loaded and every sentence provides key information. Perfectly concise and well-structured.

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

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

Given the tool's simplicity (introductory, no parameters, no output schema) and the presence of clear annotations, the description is complete. It tells the agent exactly what the tool provides and that it is the starting point.

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

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

The tool has zero parameters, so the baseline score is 4. The description does not need to add parameter semantics, and it does not contradict the schema.

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

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

The description clearly states the tool's purpose: explaining what scry is, differentiating free vs paid on the x402 HTTP API, and describing the honest-scope card. The phrase 'Start here' indicates it is the introductory tool. This is specific and distinct from sibling tools.

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

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

The description implies usage by saying 'Start here,' suggesting it is the first tool to use. However, it does not explicitly state when not to use it or provide direct comparison with alternatives. The guidance is clear in context but lacks explicit exclusions.

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

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

Annotations already indicate readOnly and idempotent. Description adds that responses are LLM-generated but grounded in service docs, a useful behavioral trait not covered by 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 concise, front-loaded sentences with no wasted words. 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 simple Q&A tool with one parameter and no output schema, description covers purpose, behavior, and knowledge base. Adequately complete given complexity.

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

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

Only parameter 'question' is self-explanatory from context. Description does not elaborate, but schema coverage is 0% and the parameter's role is clear from 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?

Description clearly states the tool's purpose: asking a help bot about service usage (endpoints, JSON shapes, prices). It distinguishes from siblings like 'about' or 'docs' by specifying the scope of questions.

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?

Implies usage for questions about the service, but does not explicitly state when to use alternatives or when not to use this tool. No guidance on exclusions.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds that the tool is 'Scored, hashed and discarded: nothing is stored', disclosing processing and storage behavior. 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 concise sentences front-loaded with the main purpose. Every sentence adds value, no 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?

No output schema and no parameter explanations leave the agent guessing about return values and input formatting. The description covers high-level behavior but omits details needed 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 0%, but the description does not describe the parameters 'turns' or 'context_key' at all. The purpose gives some hint (turns likely relate to a trace), but not enough for the agent to know how to populate them.

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 it is a 'Free, UNSIGNED channel-coupling read of a trace (the meter's demo path)', specifying the verb (read), resource (trace/demo path), and distinguishing it from signed reads. It explicitly says 'Not an attestation', differentiating it from sibling tools that may perform attestations.

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

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

The description explicitly says when to use (free unsigned read) and when not to ('Not an attestation — pay the x402 endpoint for the signed read'), providing a clear alternative for the signed version.

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 discloses that the tool is 'token-efficient and free', the exact behavior for specific names, and the overall structure of what different names return. It enriches understanding without contradicting the annotations.

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

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

The description is compact and densely structured with clear label-colon patterns. It packs substantial information into a short space. The opening phrase is a bit vague, but overall every sentence adds value and the structure aids scanning.

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

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

For a single-parameter documentation tool with no output schema and strong annotations, the description covers default behavior, special named docs, and the general fallback. It is sufficiently complete, though it doesn't mention error handling for unknown names beyond implying they are treated as doc identifiers.

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

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

Schema coverage is 0%, so the description carries full responsibility. It thoroughly explains the 'name' parameter: empty name gives the doc shelf, special names like 'start' and 'catalog' give specific content, template filenames return raw files, and any other name is a doc. It also provides examples, making parameter usage exceptionally clear.

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

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

The description clearly indicates the tool provides documentation content, with a parameter selecting the specific doc. It distinguishes itself by being the comprehensive 'whole written surface' and mentions special key names. However, it lacks a direct verb like 'retrieves' and is somewhat cryptic in the opening 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?

It gives contextual usage advice ('read this before working the board' for 'start') and notes that 'catalog' covers reads deliberately not tools. Yet it does not explicitly compare to sibling tools like 'familiar' or 'about', nor does it say when not to use this tool.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds context about the sealed nature and minting process via 'prepare', but does not fully disclose behavioral traits like error conditions or rate limits. 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 overly long and stylized with poetic language and punctuation (·, —), which reduces clarity. While it structures parameter info, it could be more concise and front-loaded.

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

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

Given the complexity (3 params, no output schema, many sibling tools), the description covers the main options but omits output format, error handling, and prerequisites. It is partially complete but leaves gaps.

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

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

With 0% schema description coverage, the description compensates by explaining each possible value for 'what' (e.g., 'card', 'collection', 'provenance') and the roles of 'wallet' and 'token_id'. This adds significant meaning beyond the bare 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 attempts to explain the tool's function as a viewer for eidolon vessels and related data, but it lacks a clear verb+resource statement. The purpose is buried in a list of options ('what' values), making it less straightforward.

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 use this tool versus its 26 sibling tools (e.g., 'about', 'ask', 'get_reading'). The description assumes the agent knows the context, which is insufficient for correct 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?

Description aligns with annotations (readOnlyHint=true) by stating 'the free read half'. It adds behavioral details: adoption uses x402 HTTP, journal tail limit semantics, and auth_message signatures are single-use. No contradictions 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 a verbose, unstructured block of text with heavy use of slang and line breaks that hinder readability. It could be significantly more concise and logically organized into sections for each sub-command.

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 thoroughly covers parameters and sub-commands but lacks information about return values, error conditions, or output schema. Given the tool's complexity (multiple actions) and no output schema, the description is adequate but incomplete for full autonomous use.

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

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

Despite 0% schema coverage, the description explains all parameters: 'what' (with options), 'limit' (journal tail), 'familiar_id' (for page and auth_message), and 'action' (for auth_message with valid values). This compensates well for the schema's lack of descriptions.

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

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

The description details multiple sub-commands (roster, adopt, page, journal, auth_message) and explains their functions, clearly defining the tool as a read-only query interface for hosted familiars. However, the use of cryptic slang and obtuse phrasing ('the free read half', 'always honest') slightly obscures immediate clarity.

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

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

The description indicates which 'what' option to use for different purposes and warns that adoption is paid and handled via HTTP, not MCP. But it does not explicitly compare to sibling tools like 'familiar_act' or provide 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?

Beyond annotations (readOnlyHint=false, openWorldHint=true), the description reveals side effects: journaling for 'talk' and 'tick', full export bundle for 'dismiss', and the signature pass-through handshake. 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?

Well-structured with bullet-like action list, code formatting for terms. Each sentence serves a purpose, though density might challenge quick scanning. No fluff.

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 tool with no output schema, the description explains return behavior (journal, public page, export bundle) and the authentication dance. Some edge cases (e.g., what happens if action is unrecognized) are omitted.

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 has 4 parameters with 0% coverage, but description explains 'text' ties to 'talk', 'signature' is an EIP-191 signature over auth_message, and 'action' values are enumerated. This adds critical meaning the schema alone lacks.

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

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

The description uses specific verbs ('talk', 'tick', 'dismiss') tied to distinct resources and outputs, clearly distinguishing this tool from siblings like 'familiar' or 'get_reading'. Each action's effect is succinctly defined.

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 states when to use each action ('talk' for plain-English turns, 'tick' for cadence beat, 'dismiss' for retirement) and covers the signature requirement. It lacks explicit alternatives or when-not-to-use, but the 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 declare readOnlyHint, idempotentHint, and openWorldHint=false. The description adds significant context: it is a 'signed deterministic measurement' and includes an 'LLM interpretation that saw only the aggregate numbers', emphasizing that it is not a verdict. This aids agent understanding beyond annotations.

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

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

The description is two sentences long, front-loading the purpose. Every sentence adds value: the first defines the action and its nature, the second clarifies the non-binding nature of the reading. No waste.

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

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

The tool is simple (one param, no output schema). The description explains what the tool does and the nature of its output, but it does not specify the return format or what the agent can expect to do with the result. With no output schema, the description should provide more concrete details about the response structure.

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

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

The schema has one required parameter, vow_id, but the description does not elaborate on its meaning or format. With 0% schema description coverage, the description fails to compensate. The parameter's purpose is somewhat inferable from the tool name but not explicitly stated.

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

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

The description clearly states the tool's purpose: 'Consult the oracle on a vow's trajectory'. It uses specific verbs ('consult') and identifies the resource ('vow'). While poetic, it effectively communicates the tool's function. However, it does not explicitly distinguish this tool from siblings like 'play' or 'read_ledger', relying on context.

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 when one wants a reading on a vow (e.g., after taking a vow). It does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives. The usage context is implied but not fully explicated.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds substantial behavioral context: the door is open but access is not a gate, the distinction between 'who' (sworn name) and 'display' (self-declared), the requirement to derive keys locally, and that scry never holds keys or signs. This goes well beyond the annotations and provides key usage 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 long and densely metaphorical ('the door is OPEN', 'the register is the RECORD'), which obscures the key information. The most useful content is buried in a long list of 'what' values, and the structure is not front-loaded. Every sentence carries information, but the stylistic opacity and lack of clean formatting hurt 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 complex tool with 9 parameters and no output schema, the description is fairly complete. It covers access control, the various subcommands, the non-custodial safety model, and important constraints like the 'who'/'display' distinction. It lacks explicit return shapes and leaves some parameters undefined, but overall it provides enough context for an agent to understand the tool's scope and limitations.

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

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

With schema coverage at 0%, the description must compensate for all 9 parameters. It does explain several: 'what' subcommands, 'to' constraints (must be a sworn name/npub/vow id, never a raw address), 'amount' as optional, and 'vow_id' as needed for certain actions. However, it leaves 'name' and 'limit' unexplained, and the description mixes parameter semantics within narrative rather than mapping clearly to schema fields.

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

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

The description identifies the tool as 'the read + prepare half' of the talk annex on buzz/Nostr, which is a specific verb+resource and clarifies it is not a write tool. It enumerates multiple actions via the 'what' parameter (card, rooms, room, voice, message, profile, braid, tip), giving a multi-purpose but clear scope. However, it does not explicitly compare against sibling tools, relying on the 'read + prepare' 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 provides strong usage guidance: it states that any Nostr key can read and speak, explicitly warns that writing is not possible through scry and must be sent as an EVENT on the user's own socket, and emphasizes non-custodial behavior. It does not name specific alternatives but clearly delineates when to use this read/prepare tool versus other write paths.

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 basic hints (non-read-only, non-destructive). The description adds critical behavioral details: both parties consent, scry holds no keys, the event structure, and wallet-sworn bindings earn a NIP-05 name. It also mentions unbinding. This goes beyond annotations without contradiction.

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

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

The description is concise at three sentences, with the core purpose front-loaded. However, the technical jargon and dense packing of information reduce clarity. A structured format (e.g., bullet points) could improve scannability.

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 5 parameters and no output schema, the description covers binding/unbinding, consent, event format, and wallet bindings. It fails to explain the 'name' parameter, prerequisites (e.g., valid vow_id), error cases, or return values. This leaves notable gaps for an AI 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?

With 0% schema coverage, the description must compensate. It explains the 'event' and 'signature' parameters in detail but does not clarify the required 'vow_id' and 'npub' or optional 'name'. Partial compensation leaves gaps for the AI agent.

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

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

The description clearly states the tool's function: binding a Nostr key to a vow. It uses specific verbs ('Bind', 'unbinds') and resources ('Nostr key', 'vow'). It distinguishes from sibling tools like 'hive' and 'take_vow' by focusing on key-to-vow association. However, the technical density may obscure the purpose for an AI agent.

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

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

The description implies usage context (requires consent, event format) but does not explicitly state when to use this tool versus alternatives. No exclusions or comparisons to sibling tools are provided, leaving the AI agent to infer the appropriate scenario.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the read-only nature is known. The description adds that the response varies by parameter (board vs card) and mentions response aliases ('bounties' with 'quests' as an alias). However, it does not disclose pagination, error behavior, or authentication, and includes a large amount of unrelated lore and delivery instructions.

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 excessively long and rambling. The core function is covered in the first two sentences, but the following paragraphs about bounty types, payment rules, and delivery via 'play' are tangential. This makes the description over-burdened and less scannable for an agent.

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/retrieve tool with one optional parameter, the description covers the parameter semantics and basic response behavior. It does not detail the structure of the board or card, and there is no output schema to compensate. The inclusion of unrelated delivery instructions reduces focus, but the core information 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?

The input schema has a single optional quest_id with no description, so the description carries the full burden. It explains that omitting the parameter returns the entire board, while providing it returns a specific bounty's full card. It also clarifies the parameter's legacy name and the response alias, giving sufficient semantic meaning.

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

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

The description clearly states that the tool returns 'the board' (all bounties) when no quest_id is given, and 'that bounty's full card' when quest_id is provided. While phrased in lore-heavy language, it identifies the resource as the bounty board and differentiates it from sibling tools like 'vows' by focusing on SCRY bounties.

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 parameter-based usage (omit quest_id for the full board, include it for a specific bounty) and explains bounty types, but it does not explicitly name alternative tools or provide when-not-to-use guidance. The delivery instructions via 'play' are tangential and not framed as an alternative to munus.

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 beyond annotations by detailing deterministic behavior, score-blindness, and that keys never touch the server. Annotations already provide readOnlyHint=false, openWorldHint=true, etc., but the description adds concrete operational guarantees.

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 somewhat verbose and includes poetic language ('one door', 'Emission, odds and payouts...'). The key information is front-loaded, but the latter part about 'Read anything with town first' feels tangential. Several sentences could be more concise.

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

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

Given the tool's complexity (multiple parameters, actions, authentication modes), the description covers purpose, usage, parameters, and behavioral guarantees. There is no output schema, but the description mentions the index returned when called with no action. It is sufficient for an AI agent to use the tool correctly.

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

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

With 0% schema coverage, the description fully explains the parameters: action format ('subject.verb'), args as action-specific fields, vow_id and signature always top-level. It also clarifies signature is an EIP-191 signature produced locally. This is essential information not 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 states that the tool is for performing actions in the town, and also for listing actions when called with no action. The verb 'play' combined with 'Every action in the town' clearly indicates the resource. However, the phrasing is somewhat poetic (e.g., 'one door') which slightly reduces clarity. It does not explicitly distinguish from siblings but implies it's the central action tool.

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

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

The description explains when to use the tool without action (to get the index) and provides context on signature requirements for wallet vows vs. sandbox vows. It does not, however, compare against sibling tools or explicitly state when not to use it.

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

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

The description fully discloses behavioral traits beyond annotations: it is non-custodial, never sees private keys, responds honestly even before a drop is armed. The annotations (readOnlyHint=true, idempotentHint=true) are consistent with the description stating it 'moves nothing and attests nothing'. 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?

The description is relatively detailed but well-structured, with the core purpose front-loaded. Each sentence adds value, though some redundancy could be trimmed. It remains clear and informative without excessive verbosity.

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

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

Given the tool's complexity, the absence of an output schema, and the rich set of sibling tools, the description is complete. It explains return values (list card, unsigned txs, preconditions), covers multiple action paths, and sets expectations about non-execution. The context signals (no output schema, 0% schema coverage) are fully addressed.

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

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

Schema coverage is 0%, so the description must compensate. It does so by explaining the 'action' parameter with examples ('claim', 'sign', 'notary/notarize', etc.) and the 'args' parameter with an example for 'claim' (wallet: '0x…'). While not exhaustive, these examples provide meaningful context for correct usage.

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

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

The description clearly states the tool's function: generating non-custodial calldata for on-chain actions. It specifies the verb ('prepare') and resource ('calldata, unsigned transactions, preconditions') and distinguishes itself from sibling tools by emphasizing the non-custodial nature and the different actions (claim, sign, etc.).

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

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

The description provides explicit guidance on when to use specific actions (e.g., 'action=claim' for drop path, 'action=sign' for off-chain sibling index). It also warns that the tool does not execute actions ('Prepared, not executed'). However, it does not explicitly compare to sibling tools or state when not to use this tool, though the unique non-custodial aspect implies its niche.

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 provide readOnlyHint and idempotentHint, so the description's addition of 'Free forever' offers useful rate limit context. The description outlines returned data but lacks details on error behavior or authentication requirements, leaving some gaps.

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 concise sentences with no wasted words. The first sentence lists data elements; the second mentions cost. However, breaking the data into a structured list could improve readability.

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

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

For a simple read tool with one parameter and no output schema, the description provides a reasonable overview of returned data. It mentions 'public' implying no auth, but lacks detail on error cases or response format. Competent but not thorough.

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

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

There is only one parameter (vow_id) and schema description coverage is 0%. The description does not explain what a 'vow_id' is or how to obtain it, adding no meaning beyond the parameter name. The burden to clarify is on the description given the lack of schema documentation.

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 it reads a public vow ledger and lists specific data elements (vow, chain, trajectory components). The verb 'read' is unambiguous. However, it does not explicitly differentiate from siblings like 'vow_listing' or 'verify', missing a chance to clarify distinct use cases.

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 on when to use this tool over alternatives such as 'verify' or 'vow_listing'. The description does not mention prerequisites, context, or conditions that would help an agent select this tool appropriately.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds that the tool 'never renders a verdict' and is 'free forever', providing useful behavioral context. The mention of a paid endpoint is extra but not confusing.

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 longer than necessary and includes poetic language and extraneous details like 'free forever' and the paid reading note. The bullet-point structure helps, but it is not front-loaded and could be more concise.

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

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

For a read-only tool with no output schema, the description explains what is returned for each 'what' value. However, the parameter semantics issue and lack of explicit return format leave gaps. It covers the basics but is not fully complete.

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

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

The description explains the meaning of the 'what' parameter and how 'id' is used for covenant and pact. However, it states 'id required' for those types, contradicting the schema which marks id as optional with a default. The description partially compensates for 0% schema coverage but is incomplete.

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

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

The description clearly states the tool retrieves public registers (covenant, pact, witness) and explains what each type contains. It distinguishes between the three register types, but the language is somewhat poetic and could be more straightforward.

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 each 'what' value by describing the output for each register type. However, it does not explicitly guide the agent on when to use this tool over siblings like 'witness_pledge' or 'vow_listing', and the note about paid witness reading is tangentially related.

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 indicate non-readonly, open-world, non-idempotent, non-destructive. The description adds value by detailing side effects: appending to hash chain, storing public note, comparing testimony, and optional raw trace donation. Rate limiting is mentioned. No contradictions 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 concise with two front-loaded sentences. The first sentence conveys the primary action, and the second adds key details. No redundancy, but could be slightly more structured with bullet points for 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?

Given the complexity (scoring, hash chain, public note, trace donation, rate limiting) and lack of output schema, the description covers major points but omits return value, error cases, and the role of 'context_key'. Additional details would improve completeness.

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

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

Schema description coverage is 0%, but the description adds meaning for 'turns' (explaining it contains Y,M,D,context), 'note' (optional public self-account), and 'donate_trace' (donates raw trace). However, 'vow_id' and 'context_key' lack explanation, leaving gaps in parameter understanding.

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

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

The description clearly identifies the tool as a report-in on a vow, specifying the verb (score, append), resource (vow, turns), and outcome (append entry to hash chain). It distinguishes from sibling tools like 'take_vow' by its specific action of scoring turns and appending to a public chain.

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 use after taking a vow to report progress, mentioning 'demo' and 'rate-limited', but does not explicitly state when to use this tool versus alternatives like 'take_vow' or 'vow_listing'. No clear when-not-to-use or alternative guidance is 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?

The description discloses extensive behavioral traits beyond the readOnlyHint, including that 'earned: null' means unchecked, badge evidence kinds, no ranking/paid placement, and that prepare changes nothing. It also explains that numbers like price are eth_calls refused as typed fields, guiding interpretation.

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 highly verbose and stylistically ornate, using poetic language and multi-line indented lists. While informative, it exceeds necessary length and could be more concise; the format is not easily scannable.

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 no output schema, the description details every mode's return content (trimmed titles, full titles, reviews+summary, badges with evidence, signed log, desk capabilities, prepare refusals/text). It also covers edge cases like earned:null, making it complete for the tool's complexity.

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

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

With 0% schema description coverage, the description fully compensates by defining the 'what' values and their required parameters (e.g., slug for title/reviews/achievements/prepare, fields for prepare save/revert, wallet for achievements/desk). This adds meaning that the schema lacks.

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 defines 'store' as a curated game platform and enumerates distinct modes ('shelf', 'title', 'reviews', 'achievements', 'log', 'desk', 'prepare'), each with specific outputs. It distinguishes these from sibling tools by noting alternatives like wire for price data. Though multi-mode, the purpose is unambiguous.

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

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

While not explicitly naming siblings for each operation, the description provides clear usage context: use wire for price/supply/FDV/TVL/holder counts, and use 'prepare' as a dry run before wallet prompts. It also clarifies that reading is open while posting may be restricted, implying when to use this read-only tool.

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

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

Annotations indicate this is a mutation (readOnlyHint=false) with side effects (openWorldHint=true). The description adds valuable behavioral context: the tool is free, not anonymous, identity is tied to a wallet, requires an EIP-191 signature obtained from a specific endpoint, and explains the deprecation of the unsigned lane. This goes beyond annotations to disclose important behavioral traits without contradiction.

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

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

The description is relatively concise, using two sentences to convey purpose, authentication, and historical context. It is front-loaded with the core action and cadence. The historical note, while informative, adds length but earns its place by explaining a behavior change. Minimal fluff.

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

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

Given the complexity (5 parameters, no output schema), the description covers purpose and authentication well but does not explain return values, success behavior, or how parameters like agent and text interact with the GET endpoint. It is adequate but incomplete for an agent to confidently invoke without further inference.

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

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

With 0% schema description coverage, the description must compensate. It explains wallet and signature (their role and acquisition), but provides no meaning for text, agent, or cadence_hours. The reference to 'GET /api/vow/message' hints at the text's origin, but parameters like agent and cadence_hours remain unexplained. This leaves significant ambiguity for an agent.

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

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

The description clearly states the tool's purpose: 'Take a public vow: commit this agent to a declared purpose with a report-in cadence.' It specifies the action (take a vow), the resource (agent with a purpose and cadence), and distinguishes from sibling tools like vows (listing) and witness_pledge (witnessing) by focusing on creation and authentication.

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 explains that the tool requires wallet and signature for authentication and notes the historical change from an unsigned lane. However, it does not explicitly guide when to use this tool versus alternatives like witness_pledge or vow_listing, nor does it state prerequisites beyond authentication. The usage context is partially implied but lacks clear 'when-not' or 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?

The description discloses critical behavioral traits beyond annotations: that the registry is permissionless, that verification only checks byte commitments (not safety), that claims are untrusted advertisements, and that absence of conduct record is not a mark against anyone. These warnings add significant value over the readOnlyHint and idempotentHint annotations.

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

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

The description is dense and contains important information but is somewhat verbose and could be more concise. It uses bold formatting and section-like structure (e.g., 'READ THE SHAPE...') which helps, but the overall length and detail may overwhelm a casual reader.

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

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

The description covers the two modes, usage context, and important caveats about trust and verification. However, it lacks explanation of the 'refresh' parameter and does not describe the return format (no output schema). For a tool with two parameters and no output schema, it is mostly complete but has gaps.

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

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

The description thoroughly explains the 'what' parameter values ('registry' and 'publish') and their meanings, including default. However, the 'refresh' boolean parameter is not mentioned, leaving its behavior undefined. Given 0% schema description coverage, the description compensates well for one parameter but misses the other.

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 explains the tool's two modes ('registry' and 'publish') and states its purpose as retrieving on-chain tool agent registrations. The phrase 'Agent tools on-chain' and the instruction 'USE THIS BEFORE CALLING A TOOL YOU FOUND ON-CHAIN' clarify the core function. However, the description lacks a succinct verb+resource statement and is somewhat ambiguous about whether it lists or verifies.

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 states when to use this tool ('USE THIS BEFORE CALLING A TOOL YOU FOUND ON-CHAIN') and provides context about how to interpret the output (alphabetical, verification as byte matching, not safety). It does not, however, contrast with specific sibling tools like 'register' or 'verify' or state when not to use this tool.

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

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

Annotations already indicate read-only and idempotent. Description adds that prices/odds are deterministic and score-blind (no meter movement), which is beyond annotations. No contradictions.

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

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

Description is dense and front-loaded with main purpose. Every sentence adds value, but the long list of options in a paragraph could be more structured (e.g., bulleted). Still concise given the amount of info.

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 complexity (many sub-reads, 3 optional params, no output schema), description is comprehensive. Covers all use cases, mentions return nature implicitly, and provides necessary context. No output schema needed as return is the requested data.

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 has no descriptions (0% coverage), so description carries full burden. It explains 'what' in detail (list of options), 'vow_id' for personal data, and 'id' for specific contexts. Adds significant meaning beyond schema, though mapping could be clearer.

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 it is for reading everything in the town, free. It lists many specific info types, distinguishing it from sibling tools like 'play' which are for acting. However, the primary purpose could be more succinctly summarized.

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 guidance on default values, when to pass vow_id, and alternatives for acting (play). It mentions that 'crier' is the default and explains usage for several what options. It does not explicitly list when not to use, but context is sufficient.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, so the tool is safe to call. The description adds valuable context: 'Nothing here is a measurement; it is the apparatus you audit one with.' This clarifies the tool's role beyond the annotations, explaining it returns audit artifacts rather than measurements.

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 well-structured with a clear lead sentence followed by a labeled list. Each item is necessary for explaining the parameter. However, it is slightly verbose with extra formatting (newlines and indentation) that could be trimmed while preserving clarity.

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

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

The tool is low-complexity with one parameter fully described. No output schema is present, but the description implies return types (e.g., signed data, schemas) adequately. It could mention the output format briefly, but overall it provides sufficient information for an agent to understand and invoke the tool correctly.

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

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

The input schema has 0% description coverage for parameters, but the description fully compensates by listing all possible values for 'what' (pubkey, canary, etc.) with detailed explanations. This adds meaning far beyond the schema, which only shows a default of 'card'.

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

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

The description clearly states the tool's purpose: 'Check scry itself, rather than taking its word.' It lists specific verification categories (pubkey, canary, etc.), each with a brief explanation, making the action and resource crystal clear. It distinguishes from sibling tools by focusing on auditing rather than data retrieval or actions.

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 does not explicitly provide when-to-use or when-not-to-use guidance. It implies usage for auditing scry but lacks comparisons to sibling tools like 'about' or 'read_ledger'. The context suggests it's for verification, but no direct exclusions or alternatives are mentioned.

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

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

Annotations show readOnlyHint=false, destructiveHint=false, etc. The description adds that it is 'Wallet-signed only' and that it can attach or update, which aligns. However, it doesn't detail side effects beyond the schema.

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

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

The description is front-loaded with the primary action and purpose. It is packed with useful information but slightly verbose in conveying signing and reading instructions. Could be tightened.

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

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

Given 4 parameters, no output schema, and sibling tools, the description covers core functionality, usage constraints, and retrieval method. Lacks details on error handling or ordering guarantees beyond 'alphabetically, never ranked'.

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

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

Schema coverage is 0%, so description must compensate. It mentions 'vow_id', 'services', and 'endpoint' indirectly ('where to reach you'), and 'signature' via 'Wallet-signed only'. But it lacks explicit mapping to schema fields and format details.

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

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

The description starts with 'SELL — attach (or update) a public services listing to a wallet vow', clearly stating the action and resource. It differentiates from sibling tools like 'vows' by specifying it creates/updates a directory entry, not just reads.

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 states when to use: 'Wallet-signed only', and provides an alternative: 'Read it back with vows(listed=true)'. It also hints at when not to use with 'no accountable identity is just spam'.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral traits: it 'lists, never ranks' and describes what is returned (report counts, missed-window status, live conduct record when listed). This adds value beyond the annotations.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence adds value. No extraneous text.

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

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

For a tool with one parameter and no output schema, the description covers the output shape (list with counts and status), the parameter semantics, and points to the sibling tool for full records. It is complete for its complexity.

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

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

The single parameter 'listed' has no schema description (0% coverage), but the description explains its effect in detail: narrowing to the directory of sworn agents with live conduct records. This fully compensates for the schema gap.

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

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

The description clearly states it is the public register of all vows, with report counts and missed-window status. It explicitly distinguishes itself from the sibling tool read_ledger for individual agent records, making the purpose unambiguous.

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

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

The description explains the effect of the 'listed' parameter (narrows to directory) and directly says to use read_ledger for an agent's full record, providing explicit guidance on when to use this tool vs. 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?

The description adds rich behavioral details beyond the annotations: it mentions returning 'conduct record, soulbound reputation, hive reach, their house on the map' for a handle, and for no handle explains alphabetical ordering, lack of ranking, and filtering by 'q' and 'has'. No contradictions 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 well-structured, starting with a clear metaphor, then explaining two modes. It is concise enough but contains slightly more detail than necessary; however, it 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 description covers the main behavior and return types for both use cases, even without an output schema. It does not mention pagination or limits, but for a directory tool it is fairly 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?

Since schema description coverage is 0%, the description fully compensates by explaining the 'handle' parameter for identity lookup, 'q' for name substring filtering, and 'has' for presence filtering. Each parameter's purpose is clearly stated.

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 defines the tool as a 'town phone book' that either returns an identity's full page when a handle is provided or lists all identities alphabetically without a handle. It distinguishes itself from sibling tools by focusing on identity lookup and directory browsing.

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 explains when to use the tool (with a handle for detailed info, without handle for browsing) and provides filtering options, but does not explicitly state when not to use it or compare to sibling tools like 'familiar' or 'about'.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds important behavioral details: disclaimers ('NOT advice', 'NOT a measurement'), specific data sourcing (e.g., 'reserves off balanceOf', 'Swap events'), and edge case behavior ('pool with no deployed token says so instead of reading zero'). This exceeds what annotations alone provide.

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

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

The description is verbose and poetic, using unconventional phrasing (e.g., 'money never moves a meter number'). While it packs information, it lacks concise bullet points or clear sectioning, making it harder for an AI to parse quickly. Could be more efficient.

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

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

The description covers multiple data types and provides some context, but it omits explicit parameter descriptions, usage scenarios, and output details. For a read-only tool without output schema, the description is moderately complete but could be more systematic.

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

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

With 0% schema coverage, the description is the sole source for parameter meaning. It partially explains 'limit' (caps day window for pools) and 'kind' (filters event type for pulse), and implies 'what' by listing options. However, not all parameters are fully documented (e.g., 'what' default is mentioned but no explicit syntax), leaving gaps.

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

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

The description clearly states the tool provides 'the town's telemetry' and lists specific data types (tape, pools, holders, ticker, pulse), each with a brief explanation. It distinguishes the tool as a read-only data source, but the poetic language may obscure the core purpose for an AI agent.

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

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

The description does not explicitly state when to use this tool versus siblings like 'get_reading' or 'read_ledger'. It describes what data is available but offers no alternative tool comparisons or contextual guidance on choosing between them.

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

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

Annotations indicate readOnlyHint=false (modifies state) and openWorldHint=true (potential side effects). The description adds that the pledge is 'free, public forever' and that breach flags are computable, and emphasizes key security ('keys never leave you'). No contradictions 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 about 40 words in two sentences. It front-loads the purpose and adds security context concisely without redundant information.

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

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

Given no output schema, the description covers core behavior (pledge details, security) but omits what the response looks like and error handling. The tool has moderate complexity with a nested object, and the description provides adequate but not exhaustive context.

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

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

Schema description coverage is 0%, so description must compensate. It lists the intended fields for the 'limits' object (allowed_tokens, denied_tokens, etc.) and mentions the signing requirement for 'signature'. However, it does not explain the format or structure of these parameters in detail, nor the signature parameter's exact role.

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

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

The description clearly states the verb 'Pledge' and the resource 'vowed wallet', and specifies the types of limits (allowed_tokens, denied_tokens, etc.). It distinguishes from siblings like 'take_vow' by focusing on setting public portfolio limits on an existing vowed wallet.

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 prerequisites (wallet-signed vows, local signing) but does not explicitly state when to use this tool vs alternatives or when not to use it. Sibling tools exist for taking vows or listing vows, but no direct comparison is given.

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