Straelo Relay

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

Annotations mark this as non-read-only, non-idempotent, and open-world, and the description justifies all three: it discloses that eligible CSI observations may be persisted best-effort, that results are point-in-time, and that an empty result is not proof of absence. That is real value beyond the annotations, though the persistence side effect is stated twice rather than expanded (e.g. failure handling).

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

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

Front-loaded with the core action, then caveats, then routing rules — good ordering. It loses a point for redundancy: the "eligible CSI observations may be persisted best-effort" sentence is repeated almost verbatim, and the bold section labels add visual noise without information.

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

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

With an output schema present, the description needn't detail return fields, and it instead covers the things structured data cannot: point-in-time semantics, the false-negative risk of empty results, and the persistence side effect. An agent has everything needed to call this correctly and interpret the result honestly.

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 the schema already constrains the single domain parameter precisely (bare hostname, no protocol/path, localhost and IPs rejected). The description adds a genuinely non-obvious disambiguation: domain is the customer domain to inspect, not a vendor domain — a distinction the schema cannot express.

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

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

States a specific verb and resource ("Scan a customer domain to detect vendors and technologies") plus the mechanism (deterministic fingerprints) and the return content (technologies with supporting evidence). It is clearly distinguishable from the vendor-customer lookup siblings, which answer different questions about the same entities.

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

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

Explicit USE WHEN and DO NOT USE WHEN blocks name three alternative tools and the exact condition that routes to each (confirmed customer base, historical adoption/removal events, transition signals). Nothing about tool selection is left to inference.

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

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

Annotations already flag readOnlyHint=true and openWorldHint=true, but the description adds non-obvious traits: it consults external providers live, identical calls can return different results (consistent with idempotentHint=false), and provider failure can yield partial or insufficient-data results. It also explicitly disclaims any execution/signing authority, closing the main safety question.

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

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

The core behavior and its external/non-deterministic nature are front-loaded, and the USE/DO NOT USE structure is easy to scan. The first sentence is dense with evaluative dimensions that could be trimmed slightly, but no sentence is filler.

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

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

With an output schema, full schema coverage, and rich annotations, the description supplies exactly the missing pieces: live-provider behavior, result variability, partial-failure outcomes, and absence of execution capability. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so each parameter is already documented, including the optional baseline_provider caveat in the schema itself. The description references the evaluated dimensions (output, fees/gas, price impact, divergence) but adds no per-parameter syntax or format detail beyond the schema, so 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 names a specific verb and resource ('Compare read-only Base swap quotes obtained from 1inch and KyberSwap') and states the concrete output taxonomy (EXECUTE_BEST, WAIT, INSUFFICIENT_DATA). It also distinguishes itself from the execution sibling ('does not execute, submit, sign, or authorize a swap').

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 USE WHEN and DO NOT USE WHEN sections define the exact condition for selection and name the alternative scenario (executing/submitting/signing a swap). The routing decision is unambiguous without opening the schema.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true, destructiveHint=false), and the description adds genuinely new operational context: no tool-specific auth or rate limit, but remote surfaces may throttle. It also implies observations can differ between calls, consistent with idempotentHint=false. Minor gap: it does not say what happens when a surface is unreachable, though the output schema covers return structure.

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

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

Purpose sentence first, then clearly delimited USE WHEN / DO NOT USE WHEN / alternative / operational notes. Every line carries routing or constraint value; the enumeration of surfaces is long but load-bearing.

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

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

With an output schema present, return values need no explanation, and the description covers the remaining burden: scope, exclusions, the sibling alternative, auth/rate-limit posture, and the fact that throttling can occur. Nothing an agent needs in order to call this correctly is absent.

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 are documented in the schema (domain constraints, previous_state semantics). The description only reinforces that this is a public-domain, observation-only check and that comparison requires a prior state; it adds no format or edge-case detail beyond the schema, so the 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?

Opens with a specific verb+resource ('Inspect a public domain') and enumerates exactly which surfaces are covered (DNS, HTTP/TLS, email posture, robots.txt, llms.txt, OpenAPI, MCP, x402, Agent Card). This is clearly distinguished from the trust-oriented sibling domain_risk_trust_decision, which is named 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?

Explicit USE WHEN (single-call observational check, or comparison against a previous state) and DO NOT USE WHEN (protocol/Agent Card/MCP validation, security certification, consumption guarantee) sections, plus a pointed redirect to domain_risk_trust_decision for merchant/domain trust. Nothing is left to inference.

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

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

Beyond the annotations, the description discloses the external data sources queried, the read-only/no-action/no-persistence posture, and limited caching. It also resolves the apparent tension between 'deterministic' and idempotentHint=false by explaining that external evidence may change between calls — context the annotation alone would leave confusing, though the response shape is left to the output schema.

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

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

Front-loaded with the decision outcome and behavior, then labeled USE WHEN / DO NOT USE WHEN sections and a concrete example. Dense but every clause contributes routing or behavioral information; no filler.

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

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

For a single-parameter decision tool with a full output schema and rich annotations, the description covers purpose, exclusions, data provenance, side-effect profile, and volatility caveat. Nothing an agent needs to select or call it correctly is missing.

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

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

Schema coverage is 100% and the schema itself already spells out the bare-hostname constraint, rejection of localhost/IP literals, and length cap. The description adds only a worked example ('domain=example.com'), which is marginal value over the schema — 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 names a specific verb and resource ('domain risk and trust evaluation'), states the decision vocabulary (ALLOW / REVIEW / BLOCK), and enumerates the evidence sources used (DNS, RDAP, TLS, HTTP/redirect, URLhaus, local indicators). An agent can distinguish it from siblings like domain_agent_discovery_check without opening either schema.

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

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

Explicit USE WHEN (interaction, onboarding, outreach, payment) and DO NOT USE WHEN clauses that name the correct alternative tool for each excluded case (domain_agent_discovery_check for health inspection, email_suitability_decision for email validation). Routing is fully determined.

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

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

Annotations already declare read-only/non-destructive/open-world, and the description adds substantial context beyond them: no SMTP probing, no mailbox-existence proof, no delivery guarantee, DNS evidence drift between calls (explaining the non-idempotent hint), latency/availability impact, and no tool-specific rate limit.

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

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

Front-loads mechanics and return shape before the bolded routing headers, and each block is scannable. Slight redundancy between the negative-capability sentence and the DO NOT USE WHEN clause (mailbox existence is stated twice) keeps it from a 5.

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

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

For a two-parameter read-only decision tool with an output schema, the description covers scope, exclusions, return structure, operational caveats, and sibling routing. An agent has everything needed to select and call it correctly.

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

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

Schema description coverage is 100% and the use_case enum plus its default-null semantics are already documented in the schema, so the description adds nothing about parameters beyond restating 'specified use case'. 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?

First sentence states a specific verb+resource (evaluate an email address's suitability) plus the exact signal set used (syntax, MX, SPF, DMARC, disposable-domain, role-account) and the decision output (ALLOW/REVIEW/REJECT). It explicitly separates itself from domain_risk_trust_decision, the nearest sibling.

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

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

Provides an explicit USE WHEN list with concrete scenarios (outbound sales, signup, transactional, CRM import, lead qualification), a DO NOT USE WHEN clause covering domain-level assessment and mailbox proof, and names the alternative tool to use instead.

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

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

Annotations already declare read-only, open-world, and non-idempotent behavior, but the description adds meaningful context beyond them: it specifies a single `eth_gasPrice` JSON-RPC call, explains that live results may change between calls (justifying non-idempotency), and explicitly states it does not estimate total cost, submit transactions, or authorize execution.

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 purpose and well-organized into USE WHEN / DO NOT USE WHEN blocks. There is minor redundancy between 'for transaction planning' and the later 'before estimating fees or preparing a transaction,' but overall it is efficient.

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

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

For a single-parameter read tool with an output schema and rich annotations, the description covers purpose, usage boundaries, alternatives, and behavioral limits. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the single `chain` parameter has a clear enum and description. The tool description mentions 'Ethereum or Base' but adds no syntax or format details beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Retrieve the current gas price for Ethereum or Base') and explicitly scopes it to transaction planning. It clearly distinguishes itself from the named sibling tools for transaction inspection and wallet balance.

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

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

Provides explicit 'USE WHEN' and 'DO NOT USE WHEN' sections with named alternatives (`evm_transaction_hash_lookup`, `evm_wallet_balance_lookup`) and the conditions that select each. Nothing is left to inference.

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

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

Annotations already declare readOnly=true, openWorld=true, idempotent=false; the description adds the reason behind non-idempotency ('live chain state may change between calls') and the single-RPC cost profile, which is real added context. It stops short of disclosing rate limits, error/failure behavior, or authentication requirements, so it is strong but not exhaustive.

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

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

Front-loaded with purpose, then cleanly segmented into USE WHEN / DO NOT USE WHEN / parameter semantics, so an agent can scan it quickly. The closing sentence restating chain, block_number, and observed_at duplicates the existing output schema and is the one piece that does not earn 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 single-parameter read tool with full annotation coverage and an output schema, the description supplies everything else an agent needs: scope, exclusions, case sensitivity, volatility of the returned value. No material gap remains.

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 the enum is already constrained, so the baseline is 3; the description goes further by stating the values are case-sensitive, a constraint the schema does not express. The only gap is that it does not say what happens on a case mismatch or invalid value.

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

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

States a specific verb and resource ('Retrieve the latest block number') plus the exact mechanism ('single eth_blockNumber JSON-RPC call') and the supported chains. It is clearly distinguishable from siblings like evm_gas_price_lookup, evm_wallet_balance_lookup, and evm_transaction_hash_lookup.

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 an explicit USE WHEN clause (synchronization, sequencing, transaction-context reference) and an explicit DO NOT USE WHEN clause enumerating the alternatives' territory: block contents, transactions, balances, gas prices, historical blocks, confirmations, finality. Nothing is left to inference.

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

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

It adds real context beyond the annotations: the engine is deterministic for identical RPC evidence, but live chain state may change between calls (which explains idempotentHint=false), and the tool never broadcasts. It also warns that ALLOW is not a guarantee of successful execution and that INCOMPLETE must not be read as ALLOW. The only gap is that it does not describe latency, rate limits, or provider failure behavior, which matter for an openWorldHint tool.

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

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

The purpose is front-loaded, followed by clearly labelled use/don't-use blocks and caveats, so an agent can scan it quickly. It runs long and the parameter-roles sentence restates ground already covered by the schema descriptions, which trims a point.

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 decision tool with an output schema, the description covers everything the schema cannot: the meaning and risk asymmetry of ALLOW/WARN/BLOCK/INCOMPLETE, determinism versus live-state drift, and the no-broadcast/no-guarantee boundary. An agent can call it and interpret results correctly without further context.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by explaining the compositional relationship — that from_address defines the simulated msg.sender context while to_address/data/value jointly form the intended transaction. Most per-field detail (hex wei units, calldata format, address patterns) is already in the schema, so no more credit is warranted.

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

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

The description opens with a specific verb and resource — 'Evaluate an intended EVM transaction before submission' — and states the output form (a machine-readable STRAELO execution decision). It is immediately distinguishable from evm_transaction_hash_lookup, which it explicitly names as the post-submission lookup path.

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 WHEN' and 'DO NOT USE WHEN' sections, and the exclusion names the alternative tool (evm_transaction_hash_lookup) plus the condition that selects it (transaction already submitted, lookup by hash). The pre-submission gating context is unambiguous.

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

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

Beyond the annotations, it discloses that live chain state may change between calls, that it does not simulate, send, sign, or assess safety, and that NOT_FOUND is a factual result. These details add meaningful behavioral context for an open-world read-only lookup.

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

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

The description is front-loaded with the core purpose, then cleanly separates scope, usage conditions, exclusions, and error semantics. Despite its length, each sentence contributes useful selection or behavioral context.

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 only two fully documented parameters, existing annotations, and an output schema, the description supplies everything needed for correct selection and invocation. It also covers the key edge case of a valid but absent hash.

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 input schema already documents the chain enum and the tx_hash pattern. The description reinforces that chain selects Ethereum or Base and that lookup is scoped to the selected network, but it does not add much parameter-level 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 states a specific verb and resource: look up an EVM transaction by hash and return normalized transaction facts. It explicitly distinguishes this tool from sibling decision, gas-price, balance, and latest-block tools by describing it as a factual post-transaction lookup and listing what it does not do.

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 WHEN and DO NOT USE WHEN sections, naming the conditions that select this tool and the conditions that should route to alternatives. It also clarifies that a syntactically valid but missing hash returns NOT_FOUND rather than a validation error.

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, it discloses that results are point-in-time observations of live chain state that may change between calls, which explains the idempotentHint=false setting, and it enumerates negative capability boundaries (no solvency, ownership, or transaction-safety judgment). This is exactly the extra context annotations cannot convey.

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

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

Front-loaded with the core action and scope, then usage routing and exclusions; every sentence carries distinct information with no filler. The do-not-use list adds the historical-balance exclusion that the schema cannot express.

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

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

For a read-only, three-parameter lookup with a full output schema and complete annotation coverage, nothing an agent needs to call it correctly is missing. Response format is intentionally left to the 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 description coverage is 100%, including the 20-item cap, address pattern, and chain enum, so the schema carries the parameter burden. The description adds only the semantic distinction that ETH is always returned while the token list is optional, which is marginal beyond what the schema already states.

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

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

Names a specific verb and resource (retrieve native ETH balance for an EVM wallet), states the supported chains, and clarifies the optional expansion to up to 20 ERC-20 contracts. It also explicitly bounds the scope (no ownership, solvency, or safety evaluation), which separates it from the decision-oriented 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?

Provides explicit USE WHEN and DO NOT USE WHEN sections and names the sibling tools to route to instead (evm_transaction_hash_lookup, evm_gas_price_lookup) plus the excluded cases of historical balances and execution decisions. An agent can select or reject this tool without any inference.

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

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

Goes well beyond the annotations: declares the decision is deterministic for identical evidence, that evidence can change between calls (consistent with idempotentHint=false), that external provider latency/availability is a factor, that there is no tool-specific rate limit, and that insufficient evidence fails closed and never yields ALLOW. That failure-mode disclosure is exactly the context annotations cannot express.

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

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

Dense but purposeful, with usage and exclusion blocks clearly labeled. Slight cost: the opening sentence carries nested parentheticals, and the closing 'fails closed / never produces ALLOW' partially restates the earlier evidence-availability warning, so it is a sentence longer than strictly needed.

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

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

For a read-only, open-world decision tool with an output schema, the description supplies the missing pieces: provider provenance, determinism semantics, chain coverage, failure behavior, and explicit non-guarantees. An agent can decide whether to call it and how to interpret INCOMPLETE without further context.

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

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

Schema coverage is 100% and the schema already documents chain normalization and the address format per chain, so the code-level semantics are covered. The description adds only a provider-level nuance (Honeypot.is is EVM-only, GoPlus primary), without per-parameter format or constraint detail beyond the schema. 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?

States a specific verb+resource ('Evaluate a crypto token for agent interaction'), names the evidence providers, the supported chains, and the exact output vocabulary (ALLOW/REVIEW/AVOID/INCOMPLETE). This clearly separates it from sibling tools, which are all *other* decision types (domain_risk_trust_decision, x402_payment_preflight_decision, etc.).

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

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

Explicit 'USE WHEN' names the triggering condition and the four chains; explicit 'DO NOT USE WHEN' excludes safety/legitimacy guarantees and warns about unavailable or incomplete evidence. That is the full when/when-not pair an agent needs to route correctly.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true, idempotentHint=false), and the description adds genuinely non-obvious behavior: results come from persisted CSI history and may change as new transitions are recorded, no live scans are performed, and no state is modified — which also explains the non-idempotent hint. It further guards against misreading `REMOVED` as proof of a vendor switch or cancellation.

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

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

Front-loaded with the verb and resource, then the event definitions, then clearly delineated USE WHEN / DO NOT USE WHEN blocks, then freshness caveats. Every sentence carries distinct information; the enumerated siblings are dense but each is necessary for routing.

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

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

For a read-only lookup with a full output schema, rich annotations, and 100% schema coverage, the description supplies everything else an agent needs: what counts as an event, what it does not prove, when to prefer a sibling tool, and the data-freshness caveat. No material gaps remain.

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%: start/end boundaries, the 1-100 limit with default 100 and no pagination, and vendor normalization (judge.me -> judgeme) are all documented in the schema itself. The description only restates the UTC time-window framing, so baseline 3 applies — it adds no parameter detail 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?

States a specific verb (Retrieve) and resource (confirmed customer adoption changes for a vendor in a UTC window) and then defines the two event types with precise domain semantics (`ADDED` = `ABSENT -> PRESENT`, `REMOVED` = `PRESENT -> ABSENT` in STRAELO CSI observations). It also explicitly rules out the two most confusable siblings, so the agent can distinguish this from vendor_customer_confirmed_lookup and vendor_customer_transition_signal_lookup without opening schemas.

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

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

Contains an explicit USE WHEN clause (historical evidence of adoption/removal during a period) and a DO NOT USE WHEN clause naming three concrete alternative tools with the condition that selects each. Nothing about tool choice is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds non-obvious interpretive context: results are confined to STRAELO's confirmed coverage rather than the vendor's global customer base, and an empty result must not be read as the vendor having no customers. It also discloses returned evidence/confirmation timestamps and normalization/deduplication behavior, which materially affects how the agent should trust and present results.

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

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

Front-loaded with the core operation, then the coverage caveat, then bolded routing blocks — well structured and mostly earn-your-place. Some repetition of 'currently confirmed' and 'STRAELO coverage' across sentences costs a point but doesn't obscure anything.

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 an output schema (so return shape needn't be described), full schema coverage, and strong annotations, the description supplies exactly what structured fields cannot: coverage limits, empty-result semantics, and sibling routing. Nothing an agent needs to call and interpret it correctly is missing.

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

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

Schema description coverage is 100%, with the limit and vendor parameters fully documented in the schema (max 100, no pagination, canonical name normalization). The description adds no parameter-level meaning beyond that, 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?

States a specific verb and resource ('Retrieve confirmed customer domains currently using a specified vendor') plus the data source (STRAELO's persisted CSI coverage). It explicitly bounds the result set (only confirmed PRESENT relationships, normalized and deduplicated), which distinguishes it from the detection and history 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?

Provides explicit USE WHEN and DO NOT USE WHEN blocks, naming three concrete alternatives (customer_vendor_detection, vendor_customer_adoption_change_lookup, vendor_customer_transition_signal_lookup) with the condition that selects each. The direction of the lookup — vendor to customers, not customer to vendors — is unambiguous.

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

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

The description adds important behavior beyond the annotations: unsupported vendors may persist aggregated demand telemetry, results reflect CSI snapshots, and outputs may change between calls. These details are consistent with the non-read-only, non-idempotent annotations and help an agent understand side effects and result volatility.

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

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

The description is front-loaded with the core action, then layers usage rules, exclusions, side effects, and snapshot caveats without wasted prose. Every sentence contributes distinct 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?

Given the single fully documented parameter, an existing output schema, and clear sibling differentiation, the description provides everything needed to select and invoke the tool correctly. It also covers the side-effect and non-determinism concerns that annotations alone would not fully explain.

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

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

The schema fully documents the single vendor parameter, including its enum values, so the schema carries the detailed semantics. The description only adds "specified vendor" context and does not provide additional syntax, defaults, or constraints beyond what the schema already states, which is the expected baseline when schema coverage is high.

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

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

The description states a specific verb and resource: find customer domains with observed technology transition signals involving a specified vendor, returning prioritized signals with evidence. It also names sibling tools and explains how this tool differs from them, so an agent can distinguish it without opening other schemas.

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

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

It gives explicit USE WHEN and DO NOT USE WHEN guidance, naming the exact alternative tools for confirmed switches, adoption events, and current vendor detection. The POSSIBLE_REPLACEMENT caveat further clarifies the boundary between correlated signals and confirmed switches.

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

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

Annotations already cover read-only and idempotency, yet the description adds what the annotations cannot: no network calls, no signing, no settlement, and the decision derivation rule (mismatch to DO_NOT_PAY, material snapshot change to REVIEW, consistency to PAY). Determinism and offline semantics are exactly the behavioral context an agent needs before trusting the result.

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

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

Front-loads purpose in the first sentence, then structured USE WHEN / DO NOT USE WHEN / behavior blocks. Dense but every sentence carries distinct information; only the final derivation sentence is slightly compressed rather than 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?

Output schema exists, so return values need no explanation, and the decision enum semantics are still spelled out. Nested intent parameters, the snapshot mechanism, and the offline safety profile are all covered, leaving nothing an agent needs in order to call this correctly.

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

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

Schema coverage is 100% and nested fields are thoroughly documented, so the baseline is 3. The description earns an increment by explaining the relationship between inputs: the declared intent is compared against the supplied x402 v2 PAYMENT-REQUIRED, and previous_snapshot drives stateless material-change detection, which clarifies the third optional parameter's role.

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

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

States a specific verb and resource ('Check an x402 payment request before signing or paying') and names the concrete output (deterministic PAY, REVIEW or DO_NOT_PAY decision). The DO_NOT_USE_WHEN line separates it from execution/payment siblings such as evm_transaction_execution_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?

Explicit USE WHEN and DO NOT USE WHEN clauses give both the trigger condition and the exclusion, so an agent knows this is a verification gate, not a payment action. The boundary against execution is stated outright rather than left to inference.

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