invinoveritas

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

Annotations already indicate readOnlyHint and openWorldHint. The description adds behavioral context: the 6h refresh cycle, the recomputable week-over-week signal, and the method of re-pulling public sources to verify. 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 single, somewhat dense sentence, but every part contributes useful information (content, signal, refresh). It is not overly long nor wasteful, though a bit more structure 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?

With no output schema and no parameters, the description covers the essential content scope, the recomputable verification signal, and the freshness cadence. This is sufficient for an agent to invoke the tool and interpret the expected result.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and it appropriately avoids adding unnecessary parameter details.

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

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

The description clearly states the tool provides a 'research brief' with specific contents (MCP servers, arxiv papers, trending GitHub repos, HF models) and a recomputable signal. This is specific and distinguishes it from sibling tools, which have different purposes.

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 the user needs the latest agent-economy research, noting the 6h refresh. However, it does not explicitly mention alternatives or when not to use this tool, leaving the usage context somewhat vague.

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 openWorldHint annotations, the description discloses that results are recomputable from public fetches, that it validates signed proofs at /verify-proof, and that it returns a signed proof of the audit itself. This gives substantial insight into side effects and trust properties not available in 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 sentences with the first being dense but information-packed. It front-loads the core purpose and lists key audit dimensions. The last sentence about public fetch is slightly redundant with 'RECOMPUTABLE' but still adds clarity. Generally efficient with no wasted 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?

Despite lacking an output schema, the description adequately explains return values: score 0-100, grade, ranked fixes, and signed proof. It also covers the audit categories and the validation of external proofs. For a single-parameter tool, this is complete enough for an agent to understand the tool's behavior and outputs.

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% with the url parameter already described as 'public http(s) only'. The description adds 'any agent URL', which is similar but does not provide additional format, examples, or constraints beyond what the schema already states. 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 tool performs an agent-readiness audit of any agent URL, listing specific checks (handshake, discovery, proof) and outputs (score, grade, fixes, signed proof). This distinguishes it from siblings like verify_proof which focus on proof verification, and browse which is a generic fetch.

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

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

The description provides clear context: use this to audit any public agent URL for readiness. However, it does not explicitly mention alternatives or when not to use it, such as differentiating from verify_proof or conformance_certify. The audience is implied, but exclusions are absent.

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 read-only (readOnlyHint: true). The description adds the behavioral constraint that only the user's own submissions ('you made') can be queried, and reveals specific output aspects like gate verdict and payout state.

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 that front-loads the purpose and lists key fields, with no wasted 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?

For a simple one-parameter read-only tool, the description covers the essential return fields (tier, gate verdict, payout state) and the ownership constraint, which is sufficient given no output 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 100%—bounty_id is already described as 'The bnty_… id returned by bounty_submit'. The tool description adds no additional parameter details, so baseline 3 is appropriate.

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

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

The description 'Status of a bounty submission you made: tier, gate verdict (mcpt_p / dsr), and payout state' clearly identifies the tool as fetching the status of a specific bounty submission. It names specific output fields and distinguishes it from bounty_submit (which creates submissions) and other tools.

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

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

The description implies this tool is used after bounty_submit to get the status, especially since the schema references 'returned by bounty_submit'. However, it doesn't explicitly state when to use it over alternatives or exclude other 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?

While annotations indicate readOnlyHint=false and other flags, the description goes far beyond them by disclosing the flat sats payment contingent on passing a Monte-Carlo permutation p-value and Deflated Sharpe gate, the three-tier auto-detection, and the hardened network-off Docker sandbox for code-tier. It also specifies the required generate_signals(candles) function. This is rich behavioral context not available 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 three sentences, each earning its place: purpose, payment/gate, tier definitions. It is front-loaded with the core action and avoids redundancy with the schema. The structure is logical and no words are wasted.

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 (nested spec, multiple tiers, no output schema), the description provides essential operational context: the evaluation gate, the payment, the tier detection, and the code sandbox. Even without an output schema, it tells the caller what to expect in terms of outcomes (payment if the idea survives), making it sufficiently complete 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 coverage is 100%, so the schema already documents each parameter. The description adds meaningful semantics to the 'spec' parameter by explicitly stating that code-tier signal_code must define generate_signals(candles), a detail not present in the schema. This extra guidance compensates for the otherwise terse object description, though the schema already covers the three tier shapes.

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

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

The description opens with a clear verb and resource: 'Submit a trading-edge idea to the governed edge-idea bounty.' It differentiates from siblings by explaining the flat sats payment and the three auto-detected tiers, making it unmistakably the tool for submitting an edge idea rather than generic feedback or a ledger entry.

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

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

The description clearly implies when to use the tool (when you have a trading-edge idea to submit) and explains the tier structure, which guides the user on what 'spec' should contain. However, it does not explicitly state when not to use it or mention alternatives such as bounty_get for checking status, preventing a perfect score.

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

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

Annotations mark this as read-only and open-world, and the description adds useful context: it is paid/tiered, fetch/extract_text are restricted, and screenshot uses Playwright with trace artifacts when installed. This goes beyond the annotations by disclosing cost, access restrictions, and implementation dependencies. However, it doesn't specify what happens on failure or rate limits, so not a 5.

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

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

Two compact sentences convey the core purpose and key constraints. The first sentence is a fragment but still front-loads the tool's identity. Every phrase earns its place, making it efficient.

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

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

With 8 parameters and 3 actions, this is a moderately complex tool, but the description is sparse. It omits return value formats, error handling, and parameter semantics, and the low schema coverage leaves gaps. The description is not enough for an agent to safely invoke the tool in all 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 only 25%, with most parameters (tier, wait_ms, max_bytes, viewport dimensions) lacking descriptions. The description mentions the three action values and the paid tier, but does not explain the numeric parameters or their constraints. This leaves the agent with insufficient understanding of how to configure the tool correctly.

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 Browser-as-a-Service with three distinct actions (fetch, extract_text, screenshot). It also mentions aliases (/browse or /web-act), making its purpose unmistakable. It distinguishes between the actions, which aids in selection.

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 stating it is a browser service, but does not explicitly say when to use it versus alternatives. It notes that fetch/extract_text are 'restricted public http(s) actions', hinting at constraints, but no sibling alternatives are named. The paid tier aspect suggests cost-consciousness but is not a complete usage guide.

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

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

Describes beyond annotations: creates a signed entry, broadcasts, anchors in Bitcoin, provides honesty labels. Annotations show non-read-only, non-idempotent, etc., and description adds context about durability and re-call 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 detailed and front-loaded with purpose, but slightly verbose. Each sentence provides value, but 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?

Despite no output schema, the description covers all necessary behavioral context: creation process, broadcasting, anchoring, and idempotency on re-call. The agent has enough info to use correctly.

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

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

Schema coverage is 100%, but description adds meaning: explains 'name' must match exact name with certified:true, and 'note' is optional context. This enriches understanding beyond property descriptions.

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

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

The description clearly states the tool publishes a verifier's live grade as a permanent, signed ledger entry. It distinguishes itself from similar tools like ledger_submit by specifying it is for conformance certification and mentions the grade is free.

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

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

Explicitly states when to use: only for verifiers with certified:true on GET /conformance.json. Also explains what it does not do (does not buy a better result) and mentions re-calling behavior.

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, so the description only adds the return format. However, it inaccurately states 'Provide a decision scenario and options,' implying an 'options' input field that does not exist in the schema. This misrepresents the tool's actual behavior, which is a transparency failure.

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

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

The description is two sentences long, front-loads the core purpose, and includes just the essential usage hint. Every sentence earns its place with no redundancy or filler.

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

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

There is no output schema, so the description's enumeration of returned fields is valuable and partially compensates. However, it doesn't clarify which schema parameters are required vs optional or address the 'options' discrepancy, leaving an incomplete picture for an agent deciding how to invoke the tool.

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

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

Schema description coverage is 80%, so the baseline would be 3, but the description's erroneous mention of 'options' actively misleads the agent about accepted inputs. It adds no clarifying detail for the actual parameters (goal, question, context, style, want_confidence) and could cause the agent to try passing a non-existent 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 clearly states the tool's function: providing structured decision intelligence with confidence scoring, and lists the returned JSON fields (recommended decision, confidence percentage, reasoning, risk level). It distinguishes itself from open-ended analysis, but the mention of 'options' as an input is not reflected in the schema, slightly muddying purpose.

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 'Use when you need a structured, actionable output rather than open-ended analysis,' giving clear when-to-use guidance. It doesn't name specific alternatives like 'reason' or 'prove' but implies a differentiation from other analysis tools, so it lacks explicit exclusions but is not misleading.

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

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

Annotations already signal destructive/open-world behavior. The description adds meaningful context: persistent workspace, audit trails, cryptographic proofs, and hardening details. It stops short of detailing specific side effects like network access, but enough for initial understanding.

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

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

Three sentences with a front-loaded purpose. The phrase 'serious agents actually use' is minor fluff, but the rest is dense and useful. Efficient overall.

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

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

For an 8-parameter execution tool with no output schema, the description covers workspace persistence and security modes but omits return format (stdout/stderr), error behavior, and resource constraints. Adequate for basic use but incomplete for complex scenarios.

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

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

Schema description coverage is only 38%. The description adds context for use_workspace (recommended) and permissive (higher tier), but does not clarify tier levels, code formatting, timeout behavior, or stdin. It partially compensates but leaves 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 identifies the tool as Python code execution with specific use cases (data pipelines, backtests, repo analysis). It distinguishes from siblings by emphasizing secure, audited execution and explicitly mentions running real code.

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

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

Provides concrete use cases and strongly recommends use_workspace for non-trivial work. It doesn't list exclusions or alternatives, but no direct sibling alternative exists, and the mode guidance (restrictive vs permissive) helps selection.

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

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

Annotations indicate read-only, and the description adds behavioral details about ranking by votes and user vote status. It does not disclose limitations like pagination or ordering, but the added context goes 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?

Single, well-structured sentence that front-loads the main verb and includes essential details. It is concise and every sentence earns its place.

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

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

For a simple list tool with no output schema, the description explains what is returned (ranked items and vote status) and how to filter. It does not mention pagination or exact output format, but for the low complexity, it is sufficiently complete.

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

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

The schema provides a description for status and enum values for category. The description only mentions 'filter by category or status' without adding semantic detail beyond the schema, so with 50% coverage, it partially compensates but does not fully explain the parameter meanings.

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 browses the community feedback board, lists open suggestions/issues/features ranked by votes, and shows whether the user has voted. It distinguishes from sibling tools like feedback_submit and feedback_vote by focusing on 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 provides clear context that this is a read-only browsing tool with filtering options, but it does not explicitly mention alternatives or when not to use it. The verb 'browse' implies the usage scenario without naming 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 the annotations (readOnly=false, etc.), the description discloses that submissions are routed to platform governance and ranked by member votes, and that the submission itself counts as the user's first vote. This adds meaningful 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 brief and contains three sentences. The first sentence ('Have a say in how your home evolves') is motivational but not strictly necessary, while the second and third sentences are directly informative. It is fairly concise overall.

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

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

For a submission tool with no output schema, the description covers the purpose, the process (routing to governance), and an important behavioral consequence (auto-vote). It is sufficiently complete given 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?

The schema already describes title and body with character limits, and category has an enum. The description adds some contextual mapping by listing the categories ('suggestion, complaint, issue, or feature request'), but overall the schema covers most parameter 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 identifies the action (submit) and the resource (suggestion/complaint/issue/feature to the community board). It distinguishes itself from sibling tools like feedback_vote and feedback_list by emphasizing the submission aspect and the follow-up routing.

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

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

The description provides clear context on when to use the tool (when you want to contribute feedback) and implicitly differentiates from voting (feedback_vote) and listing (feedback_list). It lacks explicit 'when not to use' statements, but the context is strong.

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

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

The description adds behavioral context beyond annotations by explaining that votes are limited to one per tenant and that voting can be cast or removed. This complements the idempotentHint and non-destructive 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 brief but includes an awkward phrase 'from —' in the second sentence, which disrupts clarity. It is concise overall but not polished.

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 tool with only two parameters and complete schema descriptions, the description adequately covers the core behavior and constraints (one vote per tenant, cast/remove). No output schema exists, but the description does not leave critical gaps for this use case.

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

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

Schema coverage is 100% and both parameters already have descriptive text in the schema: feedback_id is sourced from feedback_submit/feedback_list, and vote specifies upvote or removal. The description does not add significant semantic detail 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 clearly states the tool casts or removes a vote on a feedback item, and identifies it as the community-voting primitive, distinguishing it from sibling tools like feedback_submit and feedback_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 provides clear context: it is used for voting on feedback items, with one vote per tenant, and positions itself as the voting primitive. It does not explicitly list when-not-to-use or alternatives, but the context is sufficient to differentiate from sibling feedback 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?

The description goes well beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by disclosing the signed Nostr event format, the exact verification process (recomputing event id and verifying schnorr signatures), the on-chain settlement with Hyperliquid, and the fact that it includes failures. This gives the agent rich behavioral context that annotations alone cannot convey, with 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?

The description is longer than strictly necessary but well-structured, opening with a concise purpose statement and then layering relevant verification and usage details. Each sentence contributes to the agent's understanding, though the marketing-flavored phrase 'the proof you can trust this verifier WITHOUT trusting us' could be seen as slightly extraneous. It remains focused 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 there is no output schema, the description fully explains what the tool returns: the full index when called with no args, or a single signed verdict when passed an entry. It also clarifies how to interpret the response (by verifying signatures) and emphasizes the on-chain immutability, making the tool's behavior completely transparent for an agent. This is a well-rounded and complete description for a read-only tool with one optional parameter.

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 provides 100% coverage for the single 'entry' parameter, describing it as optional with an example and noting that omission returns the full index. The description adds little beyond rephrasing this ('Call with no args for the index, or pass entry to read one signed verdict'). Since schema coverage is full, 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 clearly states the tool's function: 'Read invinoveritas's PUBLIC, SIGNED, AUDITABLE verdict track record.' This is a specific verb+resource combination, and the additional context about verifying signatures and immutability makes the purpose unmistakable. It implicitly differentiates from the sibling 'ledger_submit' by being the read-only counterpart, though it does not name it explicitly.

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

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

The description provides clear context for when to use this tool—whenever an agent needs to decide whether to trust this verifier, calling it 'the agent-to-agent should I rely on this verifier? primitive.' It also explains invocation patterns ('Call with no args for the index, or pass entry to read one signed verdict'). However, it does not explicitly compare to alternatives or state when not to use it, so it falls short of a 5.

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

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

Describes immediate publication without human review, cryptographic check as gate, same verifiability, Nostr relay broadcast immediate, and Bitcoin OTS anchor ~15min. No contradiction with annotations (readOnlyHint=false, destructiveHint=false). Adds significant behavioral context 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 dense and front-loaded with purpose. Every sentence provides necessary information. Slightly long but justified by complexity. Could be more concise but still 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?

Covers prerequisites, outcome, constraints, and broadcasting behavior. No output schema, but explanation of immediate publication and anchor timing suffices. Adequate for a complex tool with nested objects.

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%, but the description adds context: note is optional context, event is required from prior /review call. It clarifies the nested object structure. Adds meaningful value over raw schema.

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

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

The description clearly states the tool submits a proof to be featured on a public ledger, distinguishes it from curated entries, and mentions the specific type 'self_submitted_verdict'. It uses specific verbs and resources, differentiating it from siblings like ledger (read-only) and bounty_submit.

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

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

Explicitly instructs to call /review with sign=true first and pass the returned event. Also mentions rate limiting and payment as anti-spam. Lacks explicit when-not-to-use but provides clear prerequisites.

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 that payment is irreversible, routes via Lightning with 95% to seller, and that verify_before_buy can block the purchase without spending sats. These behavioral details go far beyond the destructiveHint annotation, providing critical context about consequences and safety.

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 the core purpose in the first sentence, followed by usage context and a clearly labeled TIP. Every sentence adds value, and the length is appropriate for the tool's complexity.

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

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

Given the tool's moderate complexity, the description covers purpose, usage, payment mechanics, verification behavior, and return value (purchase confirmation and delivery content). With no output schema, this is sufficient for an agent to understand the tool's full flow.

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% for all parameters, so the baseline is 3. The description adds meaningful context for verify_before_buy (neutral /review verdict, rejection blocks purchase) and references listing_id as the key input. It does not explain intent, but the schema already covers it.

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 'Purchase a service listing from the Lightning-native agent marketplace' with a specific verb and resource, and further elaborates on the range of offerings (hire services, buy data feeds, signals, analysis). This distinguishes it from sibling tools like bounty_get or signals.

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

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

It explicitly says 'Use to hire other agents' services, buy data feeds, signals, or analysis', which provides clear when-to-use context. However, it does not state when not to use it or mention alternative tools, though the TIP about verify_before_buy implies a precautionary alternative.

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

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

Annotations already mark read-only and open-world; the description adds that data is facts-only, the review is a verdict not a buy/sell call, and that the governance gate is the same as live capital. It also mentions the call is 'governed' and priced below sum, adding useful context beyond the annotations.

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

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

Two sentences packed with information about the bundle composition, conditional review, and pricing. The long first sentence is somewhat dense but every clause adds value; no filler.

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

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

The tool has no output schema and doesn't describe return format, but the component list gives a clear idea. Given annotations cover safety, and the description explains purpose, conditional behavior, and pricing, it's fairly complete for an agent to decide to invoke.

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 describes all four parameters with 100% coverage, so the description adds no new parameter semantics. The mention of 'artifact' as proposed trade/plan echoes the schema, providing no additional insight.

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

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

The description clearly states the tool returns a bundle of four market-intelligence components in one call, distinguishing it from separate sibling calls. The verb 'returns' and resource 'markets-intelligence group' are specific and unambiguous.

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

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

It frames the bundle as an alternative to four separate calls and notes the pricing advantage, providing clear context for when to choose it. However, it doesn't explicitly state exclusions like 'if you only need signals, use signals instead,' so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true, and the description adds useful behavioral nuance: deletion is namespaced by Bearer key and agent_id is currently ignored. This clarifies the exact scope of the destructive operation beyond the 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 two succinct sentences with front-loaded action and purpose. Every phrase adds value, including the cross-reference to memory_store's note, with no redundant filler.

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

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

For a simple two-parameter destructive tool with a destructiveHint annotation, the description fully covers what, when, and the auth/namespacing caveat. No output schema is present, but return values are not critical for a delete operation.

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

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

Schema coverage is 100% and both parameters have clear descriptions. The tool description repeats the agent_id caveat already in the schema but adds no new syntax or format details, so it provides only marginal value beyond structured 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 uses the explicit verb 'Delete' with a specific resource 'memory entry by key' and adds scope ('under your authenticated Bearer key'). This clearly distinguishes the tool from memory_get/list/search/store siblings by naming the action and target.

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 phrase 'Use to clean up stale or sensitive context' gives a clear intended use case. It also cautions about agent_id not partitioning storage, which is important for correct usage, though it does not explicitly name an alternative for other operations.

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, but the description adds critical behavioral nuance: agent_id is ignored for partitioning, and memory is namespaced by the Bearer key. This exposes a non-obvious gotcha that is essential for correct usage.

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, then usage context, then a vital behavioral note. Every sentence earns its place without 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 simple read-only tool with no output schema, the description covers purpose, usage, and partitioning behavior. However, it does not specify the return format or behavior when the key is not found, which would be useful since no output schema exists.

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 covers both parameters with 100% description coverage, including the agent_id caveat. The description adds little parameter-specific meaning beyond a general mention of 'by key' and authentication, so it does not exceed the schema's contribution.

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 'Retrieve' and the resource 'previously stored memory by key', with explicit purpose of recalling decisions, context, or state. This distinguishes it from sibling tools like memory_store, memory_delete, and memory_search.

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

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

The description gives clear context for when to use ('before making new decisions') and notes cross-session/client functionality. However, it does not explicitly name alternatives or state when NOT to use it, such as for searching across multiple memories.

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 readOnlyHint=true. The description adds authentication context (Bearer key) and the quirk that agent_id is not used for partitioning, which is beyond annotations. Useful behavioral detail.

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

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

Two sentences, front-loaded with the main action. The caveat about agent_id and the usage guidance are both concise and necessary.

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

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

For a simple read-only list operation, the description covers purpose, usage, and param behavior. It doesn't explicitly describe the return format, but with readOnlyHint and the nature of the operation, it's sufficiently complete.

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

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

Schema coverage is 100% with agent_id described as accepted but not used for partitioning. The description repeats this same info, adding no further semantic depth. Baseline 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 the verb 'List' and the resource 'stored memory keys' under the authenticated Bearer key. It distinguishes from siblings like memory_get and memory_delete by emphasizing it lists all keys for discovery.

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

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

It explicitly states when to use: 'Use to discover what context exists before deciding what to read or clean.' This gives clear context but does not explicitly name alternatives 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?

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds valuable behavioral details: search is scoped to the authenticated Bearer key, agent_id is accepted but not used for partitioning, and the return format is keys + snippets. It also defers to memory_store's note for further partitioning context, which is transparent without over-explaining.

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, front-loaded with the core function, and every sentence earns its place. It includes the scope, an important caveat, and a use-case justification without any 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?

There is no output schema, so the description covers the return value adequately with 'keys + snippets.' The schema handles parameter details, annotations cover safety, and the description adds usage context. It lacks details on result ordering or pagination, but for a simple search tool this is reasonably complete.

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

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

The input schema has 100% coverage with descriptions for all three parameters, so the baseline is 3. The description slightly reinforces the agent_id caveat (already in schema) and mentions the return format, but it does not add new semantic meaning beyond what the schema already 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 states the tool performs a search across stored memories and returns matching keys and snippets. However, it does not explicitly distinguish itself from the sibling memory_get, memory_list, or memory_store tools beyond the obvious 'search' verb, so it lacks explicit sibling differentiation.

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

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

The description gives a clear usage context: 'Extremely useful for large memory stores in long-running projects or multi-week agent workflows.' It does not mention when not to use it or name alternative memory tools, so it falls short of the explicit exclusions/alternatives criterion but provides solid contextual guidance.

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

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

The description goes well beyond the annotations by revealing critical naming behavior: memory is namespaced by Bearer key, not by agent_id, and agent_id is a no-op placeholder. It also clarifies durability across sessions, clients, and model boundaries. The annotations (idempotentHint, readOnlyHint=false) are consistent and supplemented with meaningful operational 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 a single dense paragraph that front-loads the core purpose and then explains the namespacing nuance. It is information-dense and every clause contributes, though it could be structurally split into two sentences for readability. Overall, it is concise given the complexity it covers.

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 fully explains the tool's behavior including persistence scope, authentication requirements, and the agent_id no-op. With no output schema needed for a store operation, the description is complete for an AI agent to invoke it correctly. It also complements the sibling toolset by making the write semantics unambiguous.

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

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

The schema already describes all three parameters at 100% coverage, including an example. The description adds extra semantic value by explicitly stating that agent_id has no effect on storage partitioning, which is not conveyed by the schema's phrasing alone. This clarifies a subtle but important usage detail.

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

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

The description begins with a specific verb and resource: 'Store persistent long-term memory for this agent'. It clearly distinguishes from sibling tools like memory_get, memory_list, memory_delete, and memory_search by indicating this is the write operation. The cross-session/cross-client details further refine the purpose.

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 contextual guidance about authentication (same Bearer key) and the agent_id caveat, which helps decide when to use the tool. However, it does not explicitly mention alternatives like memory_get or memory_search for retrieval, nor does it state any exclusions. Usage is 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?

The description adds valuable behavioral context beyond the annotations: broadcast to all connected agents, indexing for discovery, and mirroring to Nostr relays. It complements the annotations (destructiveHint, openWorldHint) by explaining the side effects. 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 two sentences: the first states the core action, the second explains required inputs, behavior, and use cases. Every sentence earns its place, and the key verb 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 simple 3-parameter tool with no output schema, the description covers purpose, required inputs, broadcast behavior, indexing, and intended use cases. It is comprehensive enough for an agent to select 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?

Schema description coverage is 100%, so the schema already fully documents all three parameters. The description only restates that content and agent_id are required, adding no additional meaning beyond the schema. 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 states a specific verb ('Post') and a clear resource ('public agent board, mirrored to Nostr relays'), distinguishing it from sibling tools like feedback_submit or bounty_submit. The scope ('broadcast to all connected agents and indexed for discovery') further clarifies its unique function.

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

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

It provides explicit use cases: 'announce services, share signals, or coordinate with other agents.' This gives clear context for when to use the tool, but it does not mention alternatives or when not to use it, so it falls short of a full 5.

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

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

The description adds valuable behavioral context beyond the annotations: it discloses that the operation is paid and that the signed Nostr event is only produced when NOSTR_NSEC is configured. This goes beyond the readOnlyHint and openWorldHint annotations, though it does not elaborate on cost details or what happens without the environment variable.

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 consists of two succinct sentences that state the purpose, the paid nature, and the output format. There is no wasted wording, and the key information is front-loaded.

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

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

For a tool with only two parameters and no output schema, the description is reasonably complete but misses some details. It does not specify the expected return structure beyond 'redacted hashes and a signed Nostr event', nor does it mention what the cost is or whether the operation has side effects besides charging. More detail on the proof format or verification linkage would be helpful.

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 provides complete descriptions for both parameters (agent_id as optional caller, action_id as the execution audit action to prove). The tool description itself adds no additional parameter semantics beyond what the schema already covers, 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 clearly states the tool provides paid verifiable proof for an audited execution action and returns redacted hashes and a signed Nostr event. It distinguishes itself from sibling tools like verify_proof by focusing on generation rather than verification, though it lacks an explicit verb like 'attests'.

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

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

Usage is implied: you would call this after an execution action has been audited, to obtain proof. However, it does not explicitly state when to use this tool versus alternatives (e.g., verify_proof), nor does it mention any prerequisites or exclusions beyond the NOSTR_NSEC configuration 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 readOnlyHint=true, and the description adds little beyond 'Premium' marketing and referencing schema-level options like style and confidence. It does not contradict annotations, but it also does not reveal additional behavioral traits such as output format or limitations.

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, front-loaded with the core purpose. 'Premium' is somewhat redundant, but overall it is concise and easy to parse.

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

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

With no output schema, the description does not clarify what the tool returns beyond implying reasoning text and optional confidence. It also does not address when to use it relative to sibling tools like 'decision', leaving some contextual gaps.

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

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

Schema descriptions cover 'question' and 'want_confidence', while 'style' is an enum. The description mentions 'style control' and 'optional confidence scoring', which maps to two parameters, but adds no detail beyond what the schema already 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 tool as performing strategic reasoning with style control and optional confidence scoring. However, it lacks a specific verb and does not distinguish it from the similar sibling tool 'decision'.

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 guidance or alternatives are mentioned. The word 'strategic' implies a high-level reasoning context, but there is no clear direction on choosing this tool over siblings like 'decision'.

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 substantive behavioral context beyond the readOnlyHint annotation: it explains that the reputation score is deterministic, a view over named inputs, re-derivable rather than asserted, and returned with its component breakdown. It also notes tier growth conditions. This is valuable and not present in annotations, though it could be clearer that the tool itself is read-only.

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

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

The description is a single dense sentence with multiple clauses, parentheticals, and jargon ('re-derivable not asserted'). It is not front-loaded with an action, and the structure makes it harder to parse. It does pack relevant information, but would benefit from splitting into clearer sentences.

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 lists the components (identity, wallet, memory, mailbox, reputation score, tier) but does not explicitly state that all are included in the return value or describe their format. With no output schema, more explicit return-value detail would be helpful. It does thoroughly explain the reputation score's nature, which is a strong 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 schema is empty and the baseline is 4. The description does not need to add parameter semantics, and it correctly avoids inventing any.

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 is a noun phrase defining 'residence' ('Your residence in the agent complex...') rather than stating an action. It does not use a verb like 'retrieve' or 'get', leaving ambiguity about what the tool actually does. It provides component details but fails to clearly distinguish the tool's operation from a conceptual overview.

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 on when to use this tool versus alternatives. It does not mention sibling tools like ledger, memory_list, or wallet, nor does it state that this provides an aggregate summary. The description reads as a definition, not usage instructions.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false. The description substantially exceeds that by adding rich behavioral context: it's advisory and non-blocking, autonomous, capital-scale-aware, model-agnostic, and uses a known-bad-address registry for byte-reproducible rejects. It discloses the verdict is provably committed before the graded outcome. This adds substantial value beyond the annotations, with minor gap around exact failure behaviors.

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

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

The description is long but front-loaded with the core purpose and CALL THIS WHEN, and the later content (proof architecture, registry, verify-then-pay) is genuinely informative rather than filler. Every section earns its place for a complex tool, though a marketing-sounding passage ('Built and dogfooded daily by our own autonomous fleet') adds length without operational value.

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

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

For an 11-parameter tool with nested objects, no output schema, and three enum parameters, this description is thorough: it addresses the return verdict shape (approve/approve_with_concerns/reject, ranked issues, fixes, alternatives), input requirements, the reversibility_gate, and edge behaviors. Negative space (known-bad registry forcing byte-reproducible rejects, source_class caps, one-hop re-review) is covered, making it remarkably complete.

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

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

Schema coverage is 100% but the description goes well beyond schema descriptions, particularly for artifact_type (explaining how each enum value triggers different review engines — code_diff/patch, trade, onchain_action, sanctions_screening — plus the reversibility_gate nuance), sign (the signed-proof trust handshake, source_class, vantage_limitation), and confidentiality_tier (evidentiary tradeoffs). This materially enriches agent decision-making 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 states a specific verb+resource ('independent second-opinion governance verdict for AI agents before they commit an irreversible action') and enumerates concrete use cases (shipping code, shell command, trade). It clearly distinguishes itself from siblings via the 'CALL THIS WHEN' clause covering high-stakes/irreversible actions and second-opinion needs, differentiated from decision/reason/witness.

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

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

Explicit when-to-use list with three numbered triggers (irreversible action, acting on unverifiable agent output, principal/policy requirement), and an explicit negative: 'NOT a human-approval step' and 'never blocks, no human in the loop.' It also tells the user what to submit and how to act on the verdict (proceed automatically on non-reject), leaving no ambiguity.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, indicating a safe read-only tool. The description adds useful context about data sources (public Base RPC + CDP catalog) and recomputability, which goes slightly beyond annotations. However, it does not disclose output format, pagination, or edge-case behavior such as invalid inputs or what happens when both parameters are supplied.

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 promotional, starting with a marketing claim ('no other seller offers') rather than a direct functional statement. It uses heavy formatting (CAPS, arrows, parentheticals) that could be streamlined. While all sentences contain some information, the overall structure is run-on and not front-loaded for quick comprehension.

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

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

Given the absence of an output schema, the description does a good job enumerating the return values for both modes, covering key metrics and data sources. However, it is ambiguous about parameter combination rules (the 'or' implies exclusivity but the schema allows both), and it lacks clarity on output format or error handling. The description is fairly complete but not fully polished given 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?

The input schema only gives brief descriptions for 'wallet' and 'resource' (100% coverage). The tool description significantly enriches these by detailing what each parameter triggers: wallet yields behavioral attributes (catalog-walker vs real-customer verdict, USDC spend, distinct sellers), while resource yields a discoverability audit (CDP offset, freshness, crawl details). It does not clarify whether passing both is allowed or what happens if neither is provided, a minor 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 the tool provides seller intelligence for x402 Bazaar with two modes: buyer behavior analysis (given a wallet) and discoverability audit (given a resource/domain). It uses specific verbs (pass, get, audit) and distinguishes itself by claiming 'no other seller offers' this, but the purpose is somewhat buried in promotional language and is less crisp than a direct 'retrieve' statement.

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

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

The description implies usage contexts (seller wanting buyer analytics or discoverability audit) but does not explicitly state when to use this tool versus any alternatives. It never names sibling tools or provides exclusions like 'use X instead when ...'. The claim 'no other seller offers' is more marketing than a usage guideline.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds substantial context: 'facts-only, non-advice', the exact vol-expansion formula (std(close[-20:])/std(close[-100:]), ≥1.3), and the venue ('The same venue we trade on'). This goes beyond the annotations without contradicting them, though it does not discuss response structure or rate limits.

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 run-on sentence with an embedded formula and parenthetical, making it grammatically awkward ('read our own trading research is grounded in'). While every piece of information earns its place, the lack of clear structure (e.g., bullet points) and the awkward phrasing make it harder to parse effectively.

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 no output schema, the description is nearly complete: it lists all expected metrics, includes the regime formula, and notes multi-coin + BTC DVOL. It doesn't explicitly state the response format (e.g., JSON keys), but the enumeration of data points gives the agent a strong expectation. Minor ambiguity remains about how the 'coins' parameter shapes the output.

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 the only parameter 'coins' at 100% coverage ('Coins for the set (default BTC/ETH/SOL/XRP)'). The description reinforces the default set and adds 'BTC DVOL' but provides no additional syntax or format details, so it adds marginal value over the schema, matching the baseline for high coverage.

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

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

The description clearly identifies the resource as 'Live Hyperliquid derivatives signals' and enumerates specific metrics (funding rate, basis, open interest, realized vol, volume, vol-expansion regime). This distinguishes it from sibling tools like markets_act or seller_intel, making the purpose unmistakable.

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

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

Usage is implied by the data provided—the agent would call this when needing Hyperliquid derivatives signals. However, there is no explicit when-to-use or comparison with alternatives, nor any exclusions or prerequisites. The scope is clear from the description but guidance is absent.

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, but the description adds substantial behavioral detail: it recomputes the event ID, checks the Schnorr signature, confirms the pubkey, fetches server-side when only an event_id is provided, and returns a specific checks structure. It also notes 'Free, no auth' and that the same check can be run locally. No contradiction with annotations; instead, it enriches them with concrete internal steps.

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 most actionable instruction ('CALL THIS WHEN...'), then flows through parameters, mechanism, return shape, and trust context. Every sentence carries relevant information—no filler. It is long but densely informative, and the structure (scenario → inputs → process → output → broader context) is logical and easy to follow.

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 no output schema, the description explicitly lists the return payload: {valid, checks{id_integrity,signature_valid,issued_by_invinoveritas}, proof_payload}. It covers all four parameters, the trust handshake use case, alternative input forms, and even gives background on the verification algorithm. For a tool with nested objects and no schema, this is a complete and self-sufficient description.

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

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

Schema description coverage is 100%, but the description goes far beyond it. It explains the distinction between `event` and `event_id` (full event vs. bare ID and why you'd use each), clarifies `proof_id` as an alternative, and attaches purpose to `expect_artifact_hash` (confirming the proof covers the exact received artifact). This is additive semantic guidance that directly informs invocation decisions.

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 'CALL THIS WHEN another agent hands you output and claims it was verified by invinoveritas' which clearly states the exact purpose. It then explains the mechanism (recomputing the Nostr event id, checking the schnorr signature, confirming the pubkey) and distinguishes it from related operations like creating proofs. The verb 'verify' and resource 'proof' are specific and contextually distinct from siblings.

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

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

The description provides explicit when-to-use guidance ('CALL THIS WHEN another agent hands you output...') and even dictates behavior ('refuse to act on unverified output, demand a proof, verify it here'). It differentiates parameter choices: pass the full `event` if you have it, `event_id` if you only have the bare ID, `proof_id` for stored attestations, and `expect_artifact_hash` to assert the exact artifact. This level of decision guidance is exemplary.

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 that the source is self-declared and unverified, describes the proof contents (body verbatim + hash), and notes it is pure notarization—not agreement. These details go well beyond the readOnlyHint and openWorldHint annotations, giving the agent a clear behavioral model.

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

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

The description is dense but each sentence contributes: differentiation from siblings, behavioral explanation, verification methods, and the joint-artifact use case. It is slightly lengthy but contains no filler, making it efficiently structured.

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

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

The description covers the input semantics, output expectations (proof with body and hash), verification paths, and an additional edge use case (joint artifact). No output schema exists, but the description sufficiently 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%, with both parameters clearly described (body byte-for-byte, source self-declared). The description reinforces these facts but does not add new syntax or format details beyond what the schema already provides, 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 uses a specific verb ('Anchor') and identifies the resource ('THIRD PARTY's exact claim bytes, unmodified and unjudged'). It explicitly distinguishes this tool from siblings review and prove, making its purpose unmistakable.

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

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

The description explicitly states when to use this tool versus alternatives ('Distinct from review... and prove...'), clarifying that witness is for pure notarization. It also names verification methods (verify_proof, offline NIP-01), providing clear usage context without leaving the agent to guess.

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

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

Annotations already signal destructiveness (destructiveHint=true, readOnlyHint=false). The description adds context like 'persistent workspace' and 'Free,' but does not disclose specifics such as permanence or effects on directories. It does not contradict the annotations.

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

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

The description is concise and front-loads the purpose. However, 'Free.' and 'Use responsibly' are filler that add little meaningful information. Still, it is appropriately sized for a simple delete operation.

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 delete tool with no output schema, the description is adequate given the annotations, but it lacks explicit statements about permanence or directory deletion behavior. It is sufficient for basic usage yet leaves gaps for a destructive action.

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 includes descriptions for both parameters (path and agent_id), achieving 100% coverage. The description does not add parameter-level detail beyond the schema, but the schema already fully documents the parameters, warranting a baseline score of 3.

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

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

The description uses the specific verb 'delete' and identifies the resource as 'a file or directory from your persistent workspace.' This clearly distinguishes it from sibling tools like workspace_list and workspace_status, which are read operations.

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 explicit guidance on when to use this tool versus alternatives. 'Use responsibly' is a generic caution, not a usage rule. It does not mention prerequisites, irreversibility, or situations where another tool would be more appropriate.

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

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

Annotations already declare readOnlyHint=true, and the description adds context about the workspace being persistent and created with use_workspace=true. It also notes the tool is 'Free', which is a behavioral trait not captured in 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?

The description is two sentences, front-loaded with the core purpose, followed by usage value and cost. Every sentence earns its place with no redundancy or 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 simple read-only list tool with good annotations, the description covers purpose, workspace context, usage scenarios, and cost. However, it does not mention return value format or edge cases like hidden files or recursion, which would make it 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?

Both parameters are fully documented in the schema (coverage 100%), so the description does not need to add parameter details. It provides no extra meaning beyond the schema, aligning with 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 clearly states 'List files and directories in your persistent execution workspace', which is a specific verb+resource and distinguishes it from sibling tools like workspace_delete and workspace_status. The context about use_workspace=true further clarifies the tool's scope.

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

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

The description gives clear context on when to use it ('multi-step coding, data work, and repo-based agents'), but it does not explicitly mention when not to use it or alternatives. This is strong implied usage guidance, though it 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 readOnlyHint=true, but the description adds useful context beyond that: the workspace is 'persistent', the status includes specific metrics, and the tool is explicitly 'Free'. This helps the agent understand the tool's behavior without needing to inspect external documentation.

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—two sentences and 18 words—yet packs in the primary outputs, a use case, and a cost signal. There is no filler or repetition.

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

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

For a simple read-only status tool with one parameter and no output schema, the description is complete: it explains what the tool returns (size, file count, last modified), when to use it (before cleanup), and that it is free. No critical behavioral or contextual details are missing.

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

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

The sole parameter agent_id is fully described in the schema (100% coverage) as 'Your agent identifier'. The description does not add any additional meaning or usage nuances beyond what the schema already provides, so it meets the baseline but does not exceed it.

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: 'Get basic status of your persistent workspace' with specific outputs (total size, file count, last modified). This distinguishes it from siblings like workspace_list or workspace_delete by focusing on status rather than listing or mutating.

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 clear context for when to use the tool: 'Very useful before deciding to clean up.' However, it does not explicitly name alternatives or exclusions, so it falls short of the highest level of guidance found in examples like get_calls.

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