Sato Hub: Build Onchain & Crypto Agents

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real context beyond them: unprefixed ids are reinterpreted via slug/alias/name rules and labelled { interpreted_as, requested, rule, note }; misses are explicitly not errors and return { miss, candidates, suggestions } with an empty record. That is precisely the failure-mode behavior an agent needs.

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 and clearly sectioned with USE WHEN / NOT FOR / RETURNS / Example, so the routing information comes first. The RETURNS block is long and partly duplicates the output schema, and the nested parentheticals make it dense, but nearly every sentence carries operational information.

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

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

For a single-parameter read tool with full schema coverage, annotations, and an output schema, this is close to complete: it covers intent, alternatives, interpretation edge cases, and miss semantics. The main redundancy is re-specifying the return shape when an output schema already 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?

Schema coverage is 100% and the schema already lists the four id prefixes, so baseline is 3. The description goes further by defining what happens with an unprefixed id and what counts as a miss, which the schema does not say. Slightly short of 5 only because the prefix enumeration is restated from the schema.

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

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

States a specific verb and resource ("Fetch one Sato Hub record") and defines what Sato Hub is ("the daily-rebuilt index of what onchain and crypto AI agents are built from"). It also distinguishes itself from both siblings by name: `search` for discovering ids and onchain_agent_get_resource for slugs.

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 clause names the precondition (you hold an id that `search` returned) and the goal (quote as plain text). NOT FOR covers two exclusions with the correct alternative for each: directory slugs go to onchain_agent_get_resource, invented ids go to `search` first.

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 readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: it discloses the write path ('Read-only unless save: true'), non-custodial behavior, the commercial self-labelling of the execution block, the enforced 'nothing is invented' rule, and semantic caveats on Sato Score and Preflight unknown. This is unusually rich disclosure.

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

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

Front-loaded with USE WHEN / NOT FOR and organized into labeled sections, so it is navigable. However it is very long and dense, with some restatement between the RETURNS field list and the later SAVE/X402 paragraphs; a tighter version would lose nothing.

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 carries the return contract itself and does so completely: it enumerates the full JSON shape, explains conditional fields (starter, execution, x402_services), and covers save semantics and caveats. Nothing an agent needs to invoke or interpret the result 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%, so the baseline is 3, but the description adds lifecycle meaning the schema doesn't fully carry: how save interacts with read-only behavior, that save returns save.share_url as a permanent signed page, and the noindex/public interplay. Marginal but genuine value above the schema text.

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 concrete verb and resource ('Turn a build goal into a full plan: stack, install steps, Preflight') and explicitly distinguishes itself from three named siblings (recommend_stack, scaffold_plan, create_agent). An agent can route to this tool versus its neighbors without opening any 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?

Opens with an explicit 'USE WHEN' condition (goal-to-install composed answer) and a 'NOT FOR' clause naming the alternative for each exclusion case, including which sibling is the lighter first call. When-to-use, when-not-to-use and alternatives are all present.

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 the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial context beyond them: the three evidence classes (declared/traced/observed), stored-profile-vs-live-read with a 'bounded budget,' the `unresolved` list with reasons, and the specific meaning of `has_observed_key_egress` as the one fact to stop on. It also states the interpretation rule ('unknown' ≠ 'none found', not a safety rating).

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 USE WHEN before detail, and organized into clear labeled blocks (USE WHEN / NOT FOR / RETURNS / RULE / json shape). It is long and repeats the return shape verbosely, but almost every sentence carries operative information rather than 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 no output schema, the description carries the full return-format burden and does so completely: it documents the sato.custody/v1 payload, the per-subject summary/answers fields, `solana_receipt`, `unresolved`, and `has_observed_key_egress`, plus worked examples. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so per-dimension baseline is 3. The description adds real value on top: it maps the alias params ('install/cmd/package/text are read as `command`; mcp/mcpServers as `config`') and explains that `{}` checks nothing and answers needs_input, which the schema alone does not convey.

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

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

States a specific verb+resource ('check what an install can do with your keys and funds') with the exact inputs it operates on (crypto package, MCP server, skill). It explicitly names the siblings it is not for (onchain_agent_preflight, onchain_agent_get_deploy_spec, onchain_agent_search_skills), so an agent can route without opening any 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?

USE WHEN gives concrete triggers ('before npm/pnpm/yarn/bun add, npx -y, pip install, uvx or claude mcp add, or before pasting an {mcpServers} config'). NOT FOR enumerates three alternative tools with the exact condition that selects 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial context beyond them: the 'no winner field and none can be derived' rule, the mandatory `caveat` naming what the data cannot settle, the clarification that Sato Score is openness/activity/verifiability rather than a safety or quality grade, and that every cell is read off live records rather than typed. These are real behavioral constraints an agent could not infer otherwise.

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 USE WHEN / NOT FOR, then returns, then the enforced rule, then an example — a sensible priority order with no filler sentences. Slightly redundant in stating the return shape twice ('RETURNS the SAME derived table' and 'RETURNS (json)'), which 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?

With no output schema, the description carries the return burden and does it well by enumerating the row labels and the JSON envelope keys, plus the caveat/rules contract. The only gap is that it says 'RETURNS (json)' without addressing the markdown-default response_format, leaving the default output form slightly ambiguous.

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 both required slug parameters are documented with examples in the schema, so the baseline is 3. The description's example invocation ({ a: 'coinbase-agentkit', b: 'solana-agent-kit' }) largely restates schema examples, and it does not explain the response_format enum or that markdown is the default, so it adds little beyond the schema.

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

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

States a specific verb (compare) and resource (two directory listings) plus the exact scope: the axes Sato Hub tracks for both. It explicitly names the siblings it is not (onchain_agent_get_resource for single detail, onchain_agent_recommend_stack for ranked stacks), so an agent can route without opening any 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?

Opens with 'USE WHEN' giving the triggering question shape ('AgentKit or Solana Agent Kit?'), then 'NOT FOR' clauses naming two alternatives with the condition that selects each. This is explicit when/when-not/alternative guidance with nothing 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?

Goes well beyond the readOnly/idempotent/openWorld annotations: it documents the no_template refusal shape (id, framework, intents, chains, mismatched), the mainnet gating rule (network=mainnet plus mainnet_risk_accepted), that last_green is never invented, that the goal is not stored or logged, and that nothing signs, holds keys or moves funds. 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?

Front-loaded with USE WHEN / NOT FOR before the mechanics, and each block (templates, policy files, enforced rule, returns) carries distinct information. It is long and dense, with the template list and returns block bordering on over-stuffing, but no sentence is pure 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 no output schema, the description supplies the full return contract (schema id, ok true/false branches, template/files/env_names/manifest/last_green fields) and an example call. For a 7-parameter generation tool this leaves nothing an agent needs 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%, so the baseline is 3, but the description adds genuine meaning: the full template-id list, the intent × framework matrix that determines no_template, network defaults (fork, testnet on request, mainnet refused), and the format default. It stops short of exhaustive per-parameter syntax, but clearly exceeds 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?

States a specific verb and resource: generate a runnable TypeScript repo from a template, with the side-effect profile ('writes nothing'). It explicitly names the siblings it is not (recommend_stack, build_plan, scaffold_plan), so an agent can disambiguate it from the rest of the onchain_agent_* family 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?

Opens with an explicit USE WHEN trigger ('someone wants the code, not advice') and a NOT FOR clause routing to two named alternatives for advice and one for plan-without-repo. The when/when-not/alternative triad is fully specified.

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 cover read-only/idempotent/non-destructive, and the description adds genuinely new behavior: the enforced rule that a number travels with its stage, method, sample and date, that it is never summed across venues/chains/stages, that the URL should be cited rather than this response, and that it errors while the report is unpublished. The 'Read-only.' line merely restates the annotation, hence 4 rather than 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?

Front-loaded with USE WHEN and NOT FOR, then returns, then rules, then example — a well-ordered structure where each block earns its place. Minor waste in presenting RETURNS twice (prose and json), but overall tight and skimmable.

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 carries the full burden and delivers: both return shapes (numbers page payload vs report finding), the field list, an example slug, an error condition, and citation rules. Nothing an agent needs to call and quote 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%: slug (path segment of a satohub.ai/numbers/<slug> URL) and response_format are fully documented in the schema, including the enum. The description restates the slug concept via the URL pattern but adds no syntax or constraints 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?

The description states a precise verb+resource: it returns the method, sample and reproduce call behind a published Sato Hub number, keyed by slug. It explicitly contrasts itself with onchain_agent_get_agent_economy (fresh measurements) and onchain_agent_get_data_freshness (surface age), so an agent can distinguish it without opening sibling 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?

Opens with an explicit USE WHEN condition (asking where a published number comes from, needing method/sample/reproduce before quoting) and a NOT FOR clause naming the two alternative tools and the situations that select them. When-to-use, when-not, and alternatives are all present.

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

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

Annotations already cover read-only/idempotent safety, but the description goes well beyond them: the exact ranking order, what 'unknown' means, that price is seller-registered rather than observed, that nothing is an endorsement, and that no hit is invented. This is unusually rich behavioral disclosure.

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

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

Front-loaded with USE WHEN, then the ranking rule, returns, and an example — a sensible order. The RULE ENFORCED block is verbose and partly restates itself ('not an endorsement' / 'never by what a seller says'), but nearly every sentence carries distinct information.

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

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

For a ranking/semantics-heavy tool with no output schema, the description documents the return shape, the evidence fields, tie-breaking, and failure modes, which is everything an agent needs to 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%, so the baseline is 3. The description mentions that need is plain words and that category/chain/max_price_usd narrow results, but adds little syntax or meaning beyond the schema's own per-parameter 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?

States a specific verb ('find') and resource ('paid x402 service') plus the ranking dimension ('ranked by observed evidence'), and the domain is tight enough to separate it from siblings like search_listings or search_resources.

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?

'USE WHEN an agent needs a paid API or data service it can call and pay per request with x402' gives an explicit trigger condition, and the no-hit guidance ('fewer words, drop a filter, another category') tells the agent how to recover. It does not, however, name a sibling alternative for when this tool is the wrong ranking model.

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 (readOnly/idempotent/non-destructive), and the description adds substantial non-obvious behavior: numbers are never additive, null means unknown not zero, rates with sample_size < 20 are flagged publishable:false, Solana identity rows are upper bounds, and Solana payment settlement is uncovered. These are exactly the caveats an agent would otherwise get wrong.

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 USE WHEN / NOT FOR before the payload detail, and each block is signposted. The RETURNS paragraph is a dense wall enumerating both response shapes, but with no output schema that burden is real rather than padding; a little tightening would help.

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

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

For a high-complexity tool with five parameters, no output schema and no required arguments, the description covers the full shape of both return variants (summary vs full), the null/unit/publishable semantics, and worked examples for the three common call patterns. 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 coverage is 100%, so baseline is 3, but the description adds the cross-parameter defaulting rule that the schema only states piecemeal: omitting venue/chain/include_platforms (and detail) yields a compact summary labelled rule 'defaulted', and detail:'full' overrides that. It also documents include_platforms' response-size cost, which the schema does not quantify.

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 opening states a specific verb and resource ('measure the onchain agent economy' via measured chain reads) and immediately scopes it to registration/launch/payment/trading counts. It names the sibling tools it is not (get_trend, get_metrics, search_agents), so an agent can route without opening any 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' condition plus a 'NOT FOR' block that names three alternatives and the exact condition that selects each ('a series over time', 'one headline ERC-8004 count', 'agents registered with Sato Hub'). This is as close to a routing table as a description gets.

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

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

Annotations already declare read-only/idempotent/non-destructive, so the safety bar is met; the description adds substantial behavioral context beyond that — miss-vs-error semantics with fallback behavior, what attestations do and don't prove, the self-configured nature of payment metadata, and the explicit 'no example slug' rationale. This is well past what annotations carry.

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 USE WHEN / NOT FOR / RETURNS, which is excellent structure. It is on the long side and the parenthetical about 'my-trading-agent' is an anecdote, but every section still serves routing or expectation-setting. Minor redundancy keeps it below 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?

With no output schema, the description carries the full burden of describing return shape, and it does so thoroughly (identity, types, chains, stack, links, payment/x402 metadata, registration, erc8004). Edge cases (unknown slug, listed-but-no-passport, directory project) are all covered.

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 both parameters are fully documented in the schema, so the description does no heavy lifting here. It reinforces that slugs are not guessable and must come from search_agents, but that duplicates the schema's own note. 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 (look up the full Sato Agent Passport manifest — sato.agent.manifest/v1 — for one registered agent by slug) and enumerates the contents. It explicitly distinguishes itself from siblings onchain_agent_get_resource and onchain_agent_search_agents, so an agent can route 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?

Leads with 'USE WHEN you are about to work with, pay or depend on a REGISTERED agent', gives an explicit 'NOT FOR' case (directory projects/frameworks) with the exact alternative tool, and instructs calling onchain_agent_search_agents first. Both the positive and negative conditions are stated, plus named alternatives.

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

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

Annotations only declare readOnly/idempotent/openWorld/non-destructive; the description goes well beyond that, disclosing provenance and methodology limits (DefiLlama TVL/stablecoin supply vs growthepie transactions/active addresses, 'never added together'), staleness fields (stale_after, changed_since), null-with-reason behavior, the reading rules of the mcp-facts/1 shape, the untrusted_text safety contract, and 'Free, no key.' This is exactly the extra behavioral context annotations cannot carry.

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 USE WHEN, then NOT FOR, then RETURNS and READING RULES — every block is load-bearing and skimmable. The READING RULES paragraph is somewhat long for a definition body, but it supplies interpretive context (fact shape, untrusted_text, changed_since) that is not available elsewhere, so the length is largely earned.

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

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

No output schema exists, yet the description specifies the full return envelope (chain, as_of, stale_after, changed_since, seven named sections, not_covered, next, meta) and what null means. For a 'everything about a chain in one call' tool with one required param, an agent has everything needed to call and interpret 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 coverage is 100%, so both parameters are already documented, including the chain id/CAIP-2/name forms and the concise/detailed enum semantics. The description's 'Example: { chain: "base" }' and the section list add marginal confirmation but no syntax or format meaning beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb ('get its dated facts in one call') and enumerates the exact fact sections returned (registry, USDC, CCTP domain, ERC-8004, RPC state-override support, x402 facilitators, activity). It explicitly separates itself from the nearest siblings by name, so an agent can distinguish it from get_contract_facts, get_x402_facilitators and list_chains without opening any 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?

The 'USE WHEN you are about to build for or deploy to a chain' trigger is concrete, and the 'NOT FOR ...' clause names four alternatives (get_contract_facts, get_x402_facilitators, get_agent_economy, list_chains) with the condition that selects each. This is the explicit when/when-not/alternatives pattern.

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

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

Annotations only cover read-only/idempotent safety, but the description goes far beyond: cursor semantics (next_since starts the window at a pre-read snapshot so nothing falls between calls, with a couple of days of overlap requiring dedupe by slug), per-lane accuracy (added exact, updated field-level diff, removed approximate), and the trap that a no-argument call is a truncated sample, not a sync. It also states 'Read-only', consistent with readOnlyHint.

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 rule and clearly sectioned (USE WHEN / NOT FOR / RETURNS / CURSOR / COVERAGE / examples). Dense but nearly every sentence carries actionable information; the COVERAGE paragraph is the heaviest and could be tightened slightly.

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 carries the return burden fully — it enumerates the response shape, counts, lanes, coverage, and full_export — and additionally explains the non-obvious default behavior and the sync contract. Nothing an agent needs to call this 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%, so baseline is 3, but the description adds real usage meaning beyond the schema: feed `since` from your previous `next_since`, a later `since` yields a shorter window and smaller answer, and `detail: "full"` overrides the compact default. Only the 90-day clamp detail is essentially restated from the schema.

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

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

States a specific operation (delta retrieval against a local copy) and its scope (added / updated / removed since last sync), and explicitly carves itself away from onchain_agent_recent_changes and onchain_agent_get_resource. An agent can pick it correctly without opening any 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 / NOT FOR blocks name the two competing siblings and the conditions that select them, and the examples map natural-language requests ('sync my copy', 'what moved recently') to concrete argument choices. Exclusion guidance 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?

Annotations already declare read-only, idempotent, openWorld and non-destructive, but the description adds far more: the at-least-one-of chain/contract/token requirement, the 'protocol needs a chain' failure mode, the truncation behavior for a contract named without a chain, undisclosed testnet exclusion, disagreement handling where both claims are surfaced and neither chosen, and the 'free, no key' constraint.

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 USE WHEN / NOT FOR / RETURNS / READING RULES structure is front-loaded and each block earns its place, especially RETURNS since there is no output schema. It is long, and the READING RULES block restates several fields already listed in the RETURNS shape, so it is slightly over-budget but not padded.

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 8 parameters, the description carries the full burden and discharges it: it documents the return envelope, the field-level reading contract (value/as_of/source_url/method/confidence_class, null+reason), staleness semantics, disagreement behavior and the token-list exclusion. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds cross-parameter meaning the schema cannot convey: that protocol implicitly requires chain ('add chain' otherwise), that a contract without a chain yields one truncated page, and that two sources disagreeing yields a disagreements block rather than a resolution. That is genuine semantics beyond the per-field docs.

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 USE WHEN clause names a specific verb-and-resource ('the canonical address or id of something on a chain and want it with its source and date') and enumerates concrete examples (Permit2, EntryPoint, USDC/CCTP domain, x402 default asset, chain registry entry). It explicitly separates itself from get_chain_card and scan_recipient, so an agent can disambiguate without opening a 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?

The NOT FOR sentence names two sibling tools by name with the condition that selects each, and adds a third exclusion ('or a token price'). The USE WHEN clause gives a positive trigger condition. This is explicit when/when-not/alternative 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?

Even though annotations declare readOnlyHint=true, idempotent, openWorld and non-destructive, the description adds rich behavioral context beyond them: the 1.5x cadence lateness rule, the stalest-step aggregation, null handling for unknown surfaces, the 'unknown never fresh' failure mode when the ledger is unreadable, and that late surfaces still serve last good data. This is far more than the annotations carry.

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 USE WHEN and NOT FOR before the detailed COVERS/RULE/RETURNS sections. Dense but well-organized; the long surface list and return-shape paragraph are borderline verbose but each earns its place for a complex tool.

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

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

Given no output schema, the description fully specifies the return shape, the per-surface and per-step fields, failure modes, and the lateness rule. Nothing an agent needs to call and interpret the tool correctly is missing.

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

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

The schema already enumerates all 26 surfaces and both parameters at 100% coverage, so the description needn't repeat them. It does add meaning by stating that omitting surface returns all of them and by giving a concrete example call, though it doesn't explain the response_format enum beyond what the schema says.

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 question the tool answers (how old is the data behind a figure) with a concrete verb and resource, and explicitly names the sibling tools it is NOT (onchain_agent_explain_number, onchain_agent_recent_changes). An agent can distinguish it from siblings without opening a 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?

Gives explicit USE WHEN conditions (before quoting a Sato Hub figure, or when a figure looks stale) and explicit NOT FOR alternatives with the sibling to use instead. 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?

Though annotations already declare read-only/idempotent/open-world, the description adds substantial non-annotation context: deploy_status semantics (verified vs self_reported, explicitly not a safety guarantee), trust_spec/trust_warnings conditions, preflight verdict caveats, and the error-with-alternatives behavior when no manifest exists. Short of 5 only because pagination or freshness/caching behavior isn't touched.

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 USE WHEN / NOT FOR / RETURNS / KEYS / PREFLIGHT / deploy_status structure is good, but the total is long and several blocks (KEYS AND MONEY, PREFLIGHT, RETURNS) restate the same return-field story, so not every sentence earns its place.

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

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

Given no output schema, the description documents the return bundle key by key (deploy_spec, preflight_summary, trust_spec, trust_warnings, agent_docs, next_step, save_stack_url), explains trust signals and their limits, and covers the no-manifest error path — everything an agent needs to call and act on it.

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

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

Schema coverage is 100%, so baseline 3; the description adds meaning by giving a concrete example slug and by spelling out the return bundle keyed to the slug, plus noting agent_docs nullability. Doesn't re-explain response_format, which the schema already covers.

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

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

States a specific verb and resource (get the deploy manifest/install steps for one picked component by slug) and explicitly positions it relative to siblings: it fires after recommend_stack/build_plan pick a component, and explicitly excludes choosing components, checking an install command, and full evidence lists with named alternatives.

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?

USE WHEN and NOT FOR blocks give explicit when-to-use, once-per-pick cadence, and named alternatives for each exclusion (recommend_stack, check_install, preflight). An agent can route correctly without opening any 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 declare read-only/idempotent/non-destructive, yet the description adds substantial behavior: the 30-entry bound, the success_rate_pct semantics rule (never 'uptime'), the score_days clamping (90 without a key, clamped never refused), absent-day semantics, and project-vs-methodology move labels. This is well beyond annotation coverage.

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 USE WHEN / NOT FOR / RULES, and each block is dense. It is long, and the RETURNS material is split across a prose paragraph and a duplicated 'RETURNS (json)' shape line, a mild redundancy that costs 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?

With no output schema, the description carries the full return-shape burden and does so: it enumerates fields (observed, tool_history, score_series, score_series_window, rules, sato_url), defines the enforced success-rate rule, and states the window bounds and gap semantics. Nothing an agent needs to call or interpret it 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%, so the baseline is 3, but the description adds real meaning: it explains that a longer score_days request is clamped (not refused) and surfaced via score_series_window, and that unmeasured days are absent rather than carried forward. That is semantic guidance the schema text does not fully carry.

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 (listing history over time) and frames the exact question it answers: whether a listing has been answering daily checks, whether its tool inventory moved, and how its Sato Score moved. It explicitly names the siblings it is not (onchain_agent_recent_changes, onchain_agent_get_resource), so an agent can route correctly without opening a 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?

Opens with an explicit USE WHEN clause tied to a single question, then a NOT FOR clause naming two alternatives and the conditions that select them. Nothing about when to prefer this tool 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for adding provenance and scope context: 'read directly from Ethereum mainnet', 'never the whole agent-token category or its aggregate market cap', and a live/checked_at freshness notion. It stops short of explaining pagination or rate limits, but the added scope constraints are genuinely 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?

Front-loaded with USE WHEN / NOT FOR / RETURNS sections and a compact inline example. Every sentence carries routing or scope information; nothing is redundant with the title or schema.

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

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

Although there is no output schema, the description inlines the full return shape (erc8004 fields and the top_agent_tokens array with each field), so an agent knows exactly what it gets back. Nothing needed to call this zero-required-parameter tool correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema, establishing a baseline of 3. The description reinforces what token_limit draws from ('curated Top Project Tokens index, only tokens of directory-listed projects') and gives an example call, but adds little syntax or format 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 names a specific verb+resource ('one current, citable headline figure') and enumerates exactly what is returned: the ERC-8004 Identity Registry registered-agent count and the curated Top Project Tokens index. It explicitly distinguishes itself from siblings get_agent_economy and get_trend by scope.

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

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

Contains an explicit 'USE WHEN' clause and a 'NOT FOR' clause that routes the agent to named alternatives (onchain_agent_get_agent_economy for venue/chain/stage counts, onchain_agent_get_trend for time series, plus a warning against token prices for trading). Both the positive and negative conditions are stated.

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

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

Annotations already cover read-only, idempotent, open-world, non-destructive. The description adds real value beyond them: source provenance (GitHub releases, project announcements, reputable RSS), the 'strongly filtered to the agent economy' scoping, and the emphasis on dated/source-attributed over undated blog posts. It stops short of discussing freshness/latency or dedup 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?

Front-loaded with the trigger condition, then a NOT FOR exclusion, then RETURNS and a concrete example. Every block is short and earns its place; 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?

There is no output schema, but the description compensates with a full RETURNS block enumerating every field (total, count, offset, has_more, next_offset, and the news item fields). Combined with filter and pagination guidance, an agent has everything needed to call and interpret 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 description coverage is 100%, so the schema already documents kind, chain, limit, offset, and response_format. The description restates these ('filter by kind ... and/or chain; paginate via limit/offset') with a worked example, adding only the minor point that kind and chain are combinable ('and/or'). 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 states a specific verb and resource (fetch dated, source-attributed news/releases in crypto AI agents) and explicitly distinguishes itself from siblings by naming onchain_agent_recent_changes and onchain_agent_get_wiki_page. An agent can tell what this returns versus those two without opening any 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?

It opens with an explicit 'USE WHEN' trigger and a 'NOT FOR' clause that names both alternatives and the conditions that select them. The kind/chain filter and pagination guidance further pin down correct invocation.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds useful behavioral detail beyond them: unknown or Deprecated slugs return errors, and agent_docs null has specific reasons rather than meaning 'no docs'. 'Read-only' is redundant with readOnlyHint, but the error and null semantics add real value.

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 USE WHEN, NOT FOR, RETURNS, and Example sections, and the routing information is front-loaded. Despite its density, every section earns its place by clarifying selection, return shape, or error behavior; the only minor redundancy is restating 'Read-only'.

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 compensates by explaining the returned JSON shape, the meaning of agent_docs nulls, and error behavior for unknown/deprecated slugs. Combined with clear sibling exclusions and an example invocation, it is complete enough for an agent to call 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 slug, response_format, and include_activity. The description confirms slug usage via the example and notes optional recent releases/posts, which maps to include_activity, but adds no syntax or format 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?

The description states a specific action and resource: judging one specific directory project, with concrete dimensions (open source, maintained, who is behind it, what it supports). It also explicitly distinguishes itself from several named sibling tools, so an agent can route correctly 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?

It provides explicit USE WHEN and NOT FOR guidance, naming alternatives for registering agents, inspecting listings, deploy specs, and slug discovery. This is exactly the when/when-not/alternatives structure that prevents tool confusion among many siblings.

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

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

Annotations already establish read-only, idempotent, non-destructive, open-world behavior, so the bar is lower, yet the description still adds real context: the enforced rule that the score is 0–100 openness/activity/verifiability and explicitly NOT a safety, security, legitimacy, or returns grade, plus the self-reported-claims caveat and the required citation URL. It is docked one point because behavior is largely conveyed by enumerating payload fields rather than stating operational traits.

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

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

Well front-loaded with USE WHEN / NOT FOR / RETURNS / RULE ENFORCED headings in a scannable order. Slightly penalized for redundancy: the return payload is described twice (prose RETURNS and the json key list), and 'Read-only' restates the annotation.

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

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

With no output schema, the description carries the full burden of describing the return payload, and it does: it enumerates every key (name, scale, components, tiers, provisional, not_in_score, computed, reproduce, dispute, caveat, url) and explains each section's content. Nothing an agent needs to call and use the tool 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?

There is one optional parameter (response_format) with 100% schema description coverage, so the schema already documents the enum and default. The description never mentions response_format or when to prefer markdown vs json, so it adds nothing beyond the schema — the correct baseline 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?

States a specific verb+resource (return the Sato Score methodology/rubric) and explicitly distinguishes itself from the two siblings that would otherwise look tempting: onchain_agent_get_resource for a single project's score and onchain_agent_get_listing_history for score movement. An agent can route correctly without opening any 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 ('about to describe, apply or compare the Sato Score — or when asked how to tell whether a project is real, maintained or open') and NOT FOR clauses that name the exact alternative tools and parameters for each excluded case. 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 cover read-only/idempotent/non-destructive/open-world, so the bar is lower. The description adds real value beyond them: auth ('Free, no key'), a provenance model (value/as_of/source_url/method/confidence_class), staleness semantics (stale_after, changed_since), and an untrusted_text safety warning — all gaps the 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?

Front-loaded with USE WHEN / NOT FOR / RETURNS / READING RULES / Example in a logical order, with zero filler sentences. It is dense and long, but the length is justified by the absent output schema — the RETURNS field enumeration has nowhere else to live.

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 fully documents the return shape (matches, status, use_instead, breaking, registry, contradicted_by, meta), and covers edge cases (ecosystem_ambiguous, unknown-vs-guess, null-with-reason) plus freshness semantics. An agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100% with per-field descriptions and enums for ecosystem and response_format, so the schema carries the burden. The description's example ({ package: 'x402', version: '1.2.0' }) illustrates input shape but adds little semantic detail about the inputs themselves. Baseline 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?

States a specific verb and resource ('which line of an SDK is current, and what replaces it') and explicitly names the sibling tools it is not (recommend_stack, get_deploy_spec, check_install, get_resource). An agent can distinguish it from all near-neighbors without opening any 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?

Opens with an explicit 'USE WHEN' trigger (writing/fixing/upgrading code that imports a crypto or agent SDK) and a 'NOT FOR' list that routes each excluded case to the correct alternative tool. When-to-use, when-not-to-use, and alternatives are all covered.

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

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

The annotations only cover read-only/idempotent safety, but the description adds substantial behavior: points are never summed across venues/chains/stages, the tool refuses to blend chains and reports which chains exist, null means UNKNOWN not zero, weekly is the citable grain and daily is never a headline, and raw rows are withheld. That is rich disclosure well beyond what annotations provide.

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

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

It is front-loaded and information-dense, but the multi-venue rule is stated twice ('A stage name alone is enough when one venue reports it; when several do... you get one separate series per venue') and the venue/stage catalogue is repeated from the schema. Some sentences do not fully earn their place, so it is adequate but not tight.

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 fully documents the return shapes (single series object and the multi-venue series array), the grain/unit fields, the rules block, and worked examples. 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 coverage is already 100%, so baseline is 3, but the description adds real semantics: which stages each venue reports, the defaulted 'registered' stage, and the rule that omitting venue yields one series per reporting venue. It complements the schema rather than merely restating 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 states a specific verb+resource with scope ('whether a measurement is going up or down') and explicitly names the siblings it is not (onchain_agent_get_agent_economy, onchain_agent_get_listing_history). An agent can distinguish it from every other sibling without opening a 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?

It opens with 'USE WHEN', gives a 'NOT FOR' exclusion naming the correct alternative tools for each excluded case, and provides four concrete example utterances mapping to calls. When-to-use and when-not-to-use are both explicit.

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

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

Annotations declare read-only, but the description adds substantial behavior the annotations cannot: near-miss slug aliasing (alias_of), directory-listing overlap (also_listing), and the key contract that an unknown slug is a miss rather than an error and returns nearest-slug suggestions. It even documents the specific edge case that 'what-is-sato-score' misses and redirects to get_score_methodology.

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?

Header-delimited USE WHEN / NOT FOR / RETURNS / Example structure is front-loaded and scannable, with the primary trigger in the first clause. The RETURNS paragraph is dense and packs aliasing, listing overlap, and miss semantics into one long block, which costs it a point but every sentence carries 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?

No output schema exists, so the description carries the return-shape burden and does so fully: it enumerates the page sections (summary, why it matters, how it works, components, examples, risks, related). Combined with miss/alias behavior and a concrete example call, an agent has everything needed to invoke and interpret results.

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, but the description goes beyond the schema by explaining slug matching semantics (near-miss and bare-slug resolution) that the schema's one-line 'wiki page slug' description does not. It does not add anything about response_format beyond what the enum already conveys.

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

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

States a specific verb and resource ('get wiki page') and immediately scopes it to 'explain a crypto-agent concept'. It distinguishes itself from siblings by naming get_resource for specific projects and get_score_methodology for the Sato Score, so an agent can route without opening any 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 clause with concrete triggers ('what x402 is', 'how agents hold wallets', 'what ERC-8004 does') and an explicit NOT FOR clause naming two alternatives with their conditions. It also points to list_wiki_pages for slug discovery, covering the full call path.

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

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

Annotations already declare readOnly/idempotent/openWorld, but the description adds far more: 'Free, no key', the meaning of carried:true (stale last-read), the not_read states (key wall, unreachable), the guard against mistaking 'none lists it' for 'all were checked', and the caveat that a cell is not a verdict on settlement. This is unusually rich behavioral disclosure.

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

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

Front-loaded with the USE WHEN/NOT FOR routing before the dense RETURNS block, and every block carries information an agent needs. The mcp-facts READING RULES block is heavy boilerplate for a single tool, which keeps it short of 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?

With no output schema, the description fully shoulders the return-shape burden, itemizing every top-level field including the optional none?, not_covered, next, changed_since and meta. Combined with the freshness/staleness semantics and the free/no-key note, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantic meaning the schema does not: it clarifies that a match reflects the facilitator's own /supported answer on as_of and does not imply the facilitator settles on that chain. The worked example ({chain, scheme, x402_version}) also clarifies the filter combination, though individual param syntax still lives in the schema.

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

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

States a specific verb+resource+scope: 'which facilitator lists a chain, a scheme and a protocol version', plus what each cell actually means. It explicitly disambiguates from three named siblings (search_resources, get_chain_card, get_agent_economy), so an agent can route without opening any 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?

Has an explicit 'USE WHEN' trigger (agent must pay or charge with x402) and a 'NOT FOR' block naming the exact alternative tool for each excluded case. Nothing about when to prefer this over its siblings is left to inference.

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

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

Annotations already cover read-only/idempotent safety, but the description adds substantive behavioral context beyond them: the rule enforced (never a signed URL, account id or project id), what 'integrity: stale_evidence' means (download withheld), the distinction between manifest_url proving bytes vs. safety, and the absence of deploy/buy modes. This is meaningful disclosure, not restatement.

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 'USE WHEN' and clearly sectioned (RETURNS, PACKAGES VS DIRECTORY, RULE ENFORCED), so an agent can scan it quickly. It is long, and the 'PACKAGES VS DIRECTORY' paragraph partly restates the earlier NOT FOR clause and the schema description, costing it the top mark.

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 carries the return-value burden and does so thoroughly: it enumerates the public fields returned, the acquisition modes, and the superseded_by semantics. Combined with the safety and integrity notes, nothing needed to call or interpret the result 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 already documents the slug's origin and its non-directory nature, so the description largely repeats structured content. It adds only the concrete example invocation, which is marginal; baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (inspect) and resource (one published package) and immediately scopes it to a package slug. It names the siblings it is not (onchain_agent_get_resource for directory listings, onchain_agent_search_listings for finding slugs), so an agent can distinguish it without opening any 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' condition tied to a prerequisite (you already hold a package slug), plus a 'NOT FOR' clause naming both alternatives and the exact tool to use instead. 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 only declare the generic safety profile; the description goes far beyond it with the two-call sign-then-submit protocol, ten-minute issued_at validity, a 5-write-per-hour limit that exempts the first call, free/no-points economics, public-from-creation and Self-Reported status, one-wallet-one-passport constraint, and named refusal codes including ip_quota. It also states what the signature does and does not prove, which is materially useful for an agent deciding whether to proceed.

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?

Despite its length, it is front-loaded with the trigger, then the exclusions, then the protocol, then limits and returns, each under a capitalised header. Dense rather than padded, though the WHAT SIGNING PROVES paragraph is slightly editorial for a tool definition.

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 carries the return burden and does so precisely, giving both the first-call shape ({ok, step, messages, issued_at, valid_until, next}) and the join shape (passport_id, slug, lookup_url, claim, note?). It also covers the edge case where an older passport merely lists a wallet, which an agent would otherwise mishandle.

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 already 100%, so the baseline is 3; the description earns extra by explaining the cross-call semantics the schema cannot: that the first call takes no signatures and returns the exact messages plus issued_at to echo back, and that claim_sha256 lets an owner link the passport later without the code reaching the server. It stops short of detailing the response_format parameter, but that is minor.

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 (join) and resource (Sato Hub passport) plus the mechanism (signing with the agent's own wallets, free, one step). It explicitly distinguishes itself from three sibling tools by name, so an agent can route without opening any 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?

The 'USE WHEN' / 'NOT FOR' structure names each alternative and the exact condition that selects it: onchain_agent_passport_action for changing an existing passport, onchain_agent_register_agent for the older form-style registration, onchain_agent_get_agent_passport for reading. Exclusions are as explicit as the inclusions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds return-shape detail (total, categories[{name,count}], sorted most-populated-first) and a deterministic-empty example. It restates 'Read-only' which the annotations already cover, so it falls just short of 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?

Front-loaded USE WHEN / NOT FOR / RETURNS / Example blocks, each earning its place with zero filler. The 'Example: {}' line is genuinely useful because no parameters are required.

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

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

No output schema exists, so the description carries the return-value burden and does so fully: field names, ordering, and an example call. Nothing an agent needs to invoke or interpret this tool 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 response_format enum is fully documented in the schema, so baseline 3 applies. The description's 'RETURNS (json)' hints at the format dimension but adds no syntax or guidance beyond the schema's own text.

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 (list categories) and immediately names what the tool is not (chain names, project search) with the sibling to use instead. An agent can distinguish it from onchain_agent_list_chains and onchain_agent_search_resources without opening a 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 you need valid category values before filtering onchain_agent_search_resources' plus a 'NOT FOR' clause routing to the correct alternatives. Both the trigger and the exclusions are stated, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety is covered. The description adds real value beyond that: the return shape, that it covers every chain in the directory, the spotlight-first ordering (Base, Ethereum, Solana…), and the 'real agent tooling vs announcement' distinction. It stops short of pagination or truncation behavior, keeping it from 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?

Front-loaded into USE WHEN / NOT FOR / RETURNS blocks with no filler; each sentence routes the agent or describes the payload. The trailing 'Example: {}' is a harmless confirmation that no arguments are required.

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

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

Although there is no output schema, the description supplies the exact return shape ({ total, chains: [{ name, count }] }), ordering, and directory coverage, so nothing an agent needs to call or interpret this tool 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?

Only one parameter (response_format) with 100% schema description coverage, so the schema already documents it fully. The description notes the payload is JSON but never explains response_format or its markdown/json enum, so it adds no meaning beyond the schema — the baseline 3 for high coverage 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+resource (list chains) with scope: every blockchain in the directory with resource counts. It explicitly names the siblings it is not (onchain_agent_list_categories, onchain_agent_get_agent_economy), so an agent can route 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?

Leads with an explicit 'USE WHEN' condition (need valid chain names before filtering onchain_agent_search_resources) and a second motivating case. 'NOT FOR' clauses name both alternatives and the exact sibling to use instead for each.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered structurally. The description adds the enumeration of returned fields (slug, title, keyword, summary, last_updated) and confirms read-only, which is useful context beyond the annotations, though it doesn't discuss caching or pagination behavior.

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

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

Three tight, front-loaded blocks (USE WHEN, NOT FOR, RETURNS) with no filler sentences. The routing information precedes the return-shape detail, which is the right ordering for selection.

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 carries the return-shape burden and does so by listing the aggregate shape { total, pages: [...] } and per-page fields. Nothing needed to select or invoke this zero-required-parameter list tool 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?

There is a single optional parameter whose schema description already covers the markdown/json enum at 100% coverage, so the schema does the heavy lifting. The description only contributes an empty Example: {} to signal no arguments are needed, which is a marginal addition. 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 names a specific verb+resource (list every Onchain Agent wiki page) and states the concrete value: obtaining slugs/titles for sourced explainer pages. It explicitly differentiates itself from onchain_agent_get_wiki_page and onchain_agent_search_resources, so an agent can distinguish it from siblings 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 explicit USE WHEN and NOT FOR clauses with named alternatives (get_wiki_page for reading, search_resources for finding projects) plus the triggering condition of needing a slug first. Both when-to-use and when-not-to-use are spelled out.

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

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

Annotations only give readOnlyHint=false and destructiveHint=false; the description goes far beyond, disclosing the 5-writes-per-hour limit, the 72-hour delay on removals/primary changes/claim codes, the full cancellation hierarchy, replay/staleness refusals, the last-wallet and primary removal guards, and what a signature does and does not prove. These are material behavioral facts an agent could not infer from annotations.

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

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

Front-loaded with USE WHEN / NOT FOR / action map / signing rules / returns / example, which is the right order for a 10-action tool. The 'WHO CAN CANCEL' block is a dense chain of nested clauses that is hard to parse in one pass, and some action/field mapping restates the schema.

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, nested-object mutation tool with no output schema, the description supplies the return shapes for both signed and unsigned calls, the sign-step contract, and stable refusal codes. An agent has everything needed to call it correctly on the first attempt.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter meaning the flat schema does not: which fields belong to which action, and the two-step flow where omitting all signatures yields the exact message plus issued_at to return. Some of this duplicates the action enum's own text, which keeps it below a 5.

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 ('change a Sato Passport') and immediately enumerates the ten concrete actions it performs. It explicitly distinguishes itself from the two obvious siblings: creating (onchain_agent_join_passport) and reading (onchain_agent_get_agent_passport).

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

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

Opens with 'USE WHEN an agent already has a Sato Passport and a wallet ON it needs to change it', then names both exclusion cases with the alternative tool to use instead. The preconditions (wallet already on the passport, signature flow) are spelled out rather than implied.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, but the description goes well beyond them: it defines verdict semantics (go/caution/no/unknown), states that 'unknown' means no record rather than something being wrong, caps the live endpoint handshake at 8 s and forbids a 'go' result from it, explains that custody can only lower a verdict, notes that nothing is stored, and that nulls carry their reason. This is unusually rich behavioural disclosure for a read-only tool.

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

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

Front-loaded with USE WHEN and NOT FOR, then lane-by-lane and return-shape sections, so an agent can skim. It is long and occasionally repetitive (the 'never a security review' caveat recurs across the token, skill and address lanes), but for a 13-parameter, five-lane tool the length is largely earned and the sectioning keeps it navigable.

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 present, the description carries the full return contract and does so: it enumerates the JSON shape (verdict, rule, target, evidence[], checked_at, caveat, rules, token?, skill?, solana_receipt?) and explains what each lane's evidence means. Combined with the lane definitions and the no-`go`-for-Solana rule, an agent has everything needed to call and interpret this 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 coverage is 100%, so the baseline is 3, but the description adds constraints the schema does not encode — 'Pass exactly one of repo, package, endpoint, agent, token, skill, x402 or address' (no oneOf in the schema) and the token+chain / address+chain lane pairings. It also explains that a null field carries its reason. That is genuine meaning beyond the per-parameter 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?

Opens with a specific verb and a concrete set of triggers ('install a package, clone a repo, connect to an MCP endpoint, pay an agent, or trade a token') and states what it produces (every evidence line with source field and date). It explicitly names the siblings it is not — onchain_agent_recommend_stack, onchain_agent_get_deploy_spec, onchain_agent_check_install, onchain_agent_scan_recipient — so an agent can distinguish it without opening any 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?

Contains an explicit USE WHEN block and an explicit NOT FOR block that routes each excluded case to a named alternative tool or lane. It also names the fallback behaviours: 'with none (or a template placeholder) nothing is checked' and the not-a-pick case. Nothing about when to select this tool versus its siblings is left to inference.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), yet the description goes further by disclosing the derivation (daily snapshot time-series + change-event log), the suppression rule (passive score/liveness drift filtered out, high-signal only), the tone taxonomy, and the concrete event kinds. This is meaningful context an agent could not get from annotations.

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

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

Front-loaded USE WHEN / NOT FOR / RETURNS / Example structure with zero filler; every sentence carries routing, behavioral, or return-shape information. Dense but not bloated.

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

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

No output schema exists, but the description supplies the full return shape ({ scope, total, changes: [...] }) including field names and the tone enum. Combined with the routing and suppression details, an agent has everything needed to call and interpret this 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 100%, so the schema already documents days, slug, limit, and response_format fully. The description's guidance on omitting vs passing slug largely restates the schema's own slug description and adds no new syntax or constraint. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('what has changed recently across crypto-agent tooling') plus a scoped variant (one project's history), and names the siblings it is not (get_changes, get_listing_history). An agent can distinguish this from every other change-related tool without opening a 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?

Opens with an explicit USE WHEN clause, then a NOT FOR clause naming two concrete alternatives (onchain_agent_get_changes for local sync, onchain_agent_get_listing_history for daily check records/score series) and the condition that selects 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/idempotent/non-destructive, but the description adds substantial context beyond them: trust_spec contents (key handling, planted-key observations, fund-movement ability, dated readings), trust_warnings semantics, the caveat that ranking is not a safety/returns judgment, and that Preflight 'unknown' means no record rather than a problem. It also discloses the caveated starter template (holds no key, signs nothing, not audited).

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 and well-organized with explicit USE WHEN / NOT FOR / RETURNS / KEYS AND MONEY sections, so the reader hits routing information first. However, the RETURNS and KEYS AND MONEY paragraphs are dense run-on sentences with heavy nested clauses that dilute 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?

There is no output schema, so the description carries the full burden of explaining returns — and it does: slot structure, per-pick fields (Sato Score, liveness, deploy-spec status, github_url, trust_spec), preflight_summary contents, honest gaps, save_stack_url, and the starter fallback. 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 the schema already documents goal, chain, max_per_slot, verified_only, and response_format — the baseline is 3. The description adds goal interpretation context (plain words, examples) and how named standards/runtimes influence picks, but no syntax or format 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?

States a specific verb+resource+scope ('goal → stack') and positions itself as the FIRST call for a build goal, with the follow-on chain to onchain_agent_get_deploy_spec spelled out. It also names the exact siblings it is not (search_resources, build_plan, create_agent), so an agent can route correctly without opening another 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?

An explicit 'USE WHEN' with concrete plain-word goal examples ('a trading agent on Base', 'an ElizaOS agent that charges via x402') plus a 'NOT FOR' block that names each alternative and the condition that selects it. When/when-not/alternatives are all present.

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 far beyond the annotations: discloses the two-step challenge/signature protocol, that unsigned registrations land PENDING for human review, that signature verification is EVM-only, that verification_status is always Self-Reported regardless of input, that the endpoint gets one live probe, and a concrete rate limit of 5 write calls an hour where the challenge call counts. These are exactly the operational constraints an agent could not infer from readOnlyHint/destructiveHint/idempotentHint.

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 USE WHEN / NOT FOR, then segmented into TWO STEPS, WHAT THE SIGNATURE PROVES, LIMIT and RETURNS, so an agent can stop reading once it has what it needs. It is long, but nearly every line carries distinct operational information; the trailing example largely restates the documented two-call sequence.

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 14-parameter, two-phase, signature-gated mutation with no output schema, the description covers the call sequence, the return payload shape for both calls, rate limits, and the trust semantics of the issued passport. An agent has everything needed to invoke it correctly on either path.

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 per-field descriptions already carry most semantics. The description still adds cross-parameter workflow the schema cannot express: which fields belong to the first call versus the second, that name is bound into the signed challenge, and that contact_email is mandatory on the unsigned path.

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 opening sentence names the concrete artifact produced (an Agent Passport at satohub.ai/agents/<slug> plus a manifest) and the verb (register/self-issue). The NOT FOR block explicitly distinguishes it from four named siblings, so an agent can route without opening any 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 with the motivating condition (agent wants a public machine-readable identity) and an explicit NOT FOR list naming onchain_agent_submit_project, onchain_agent_get_agent_passport, onchain_agent_join_passport and onchain_agent_passport_action with the distinguishing condition for 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?

Beyond the annotations (readOnly/idempotent/openWorld), it discloses the 60-second per-token cache hold, the refusal-and-no-guessing behavior for unsupported links/symbols, that price and liquidity are a single pool's listing never summed across venues, and that decoding comes from the chain where possible. These are real operational traits the annotations do not carry.

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 and clearly sectioned (USE WHEN / NOT FOR / INPUT / OUTPUT / RULE ENFORCED / RETURNS), which is good, but it is markedly over-long: the long supported-site enumeration in INPUT repeats the `input` schema description almost verbatim, and OUTPUT and RETURNS restate the same field list and pool caveat twice. Trimming the duplication would lose no 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 no output schema, the description carries the full return contract and does so thoroughly: field list including Solana-specific mint_authority/freeze_authority/token2022_extensions, the sources/gaps accounting for every figure and null, the not-found error shape, an example input, and the safety disclaimer. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, but several schema entries are just alias pointers ('Read as `input`'), so the description adds genuine meaning: a bare 0x with no chain is assumed Base and flagged via chain_assumed, `chain` must agree with the input, and a DexScreener/GeckoTerminal pool link resolves to the pool's base token. That is more than the schema alone conveys, though some of the site list is duplicated rather than added.

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 ('Resolve an address, a mint or a link to the token it is') and enumerates exactly what comes back: chain, address, name, symbol, decimals, program, main pool + liquidity, USD price. It explicitly distinguishes itself from onchain_agent_preflight and onchain_agent_route_swap, so an agent can route without opening any 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?

A dedicated 'USE WHEN' clause defines the trigger ('someone dropped a contract address, a Solana mint or a link and the next step needs to know what it IS'), and 'NOT FOR' names the exclusions with the replacement tool for each (preflight, route_swap, price source). This is explicit when/when-not/alternative coverage.

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

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

Annotations already establish read-only, idempotent, open-world behaviour, but the description goes well beyond them: it declares that a route is a recommendation rather than ground truth, that ERC-8004 registration proves only a claim, that wallet_verified proves only the key, that a probe proves only one answered handshake, that null feedback ranks below zero, and that no job-outcome data exists. It also discloses the pool limitation (passport-less on-chain agents are absent, absent ≠ unqualified) and that failure returns `unknown` with a reason rather than a weak pick.

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?

Long, but organised into labelled blocks (USE WHEN, NOT FOR, RULE ENFORCED, COVERAGE, RETURNS) with the routing condition front-loaded, so the size is justified by the tool's semantic weight. It is dense enough that a reader must parse several clauses to extract the return contract, which keeps it just short of maximally tight.

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 carries the full return contract inline (route/chosen_by/alternatives/caveat plus the unknown branch, preflight, candidates_considered, probed, coverage, rules), and it also supplies the enumeration-coverage caveat and the null-feedback ranking rule. Nothing needed to interpret or trust a result 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 the per-parameter semantics are already carried by the schema (chain filters the passport pool, capability is matched against name/types/services, requires_mcp/x402 are declarations only). The description adds value by supplying a concrete combined invocation example ({ capability, chain, requires_mcp }) and by framing these as pool filters rather than registry lookups, which is slightly more than the baseline.

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

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

States a precise verb+resource ('choose/route an agent for a task') and immediately pins the differentiator: the pick is explained by registration, service, feedback and liveness. It explicitly names the two sibling tools it is not (onchain_agent_search_agents, onchain_agent_get_agent_passport), so an agent can separate it from its nearest neighbours without opening a 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?

Opens with an explicit 'USE WHEN' condition and a 'NOT FOR' clause that routes to two named alternatives with their triggering conditions ('browsing registered agents with filters', 'one agent's manifest'). There is no residual inference required about when this tool is the right choice.

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

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

Annotations only cover read-only/idempotent/open-world safety; the description adds substantial behavior beyond them: non-custodial (never deploys, signs, holds keys), the Clanker lane returns a prepared config the caller signs, other venues are recommend-only, and the fee is disclosed on every response including 0. The 'null is unknown, never zero' rule is also genuinely non-obvious semantics.

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 directive headers and the when-to-use rule before the mechanics; every section (RULE ENFORCED, NON-CUSTODIAL, THE FEE, RETURNS) carries distinct information. It is on the long side, but the length is justified by a complex, high-stakes domain, so only minor trimming is possible.

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

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

No output schema exists, and the description fully specifies both return shapes (success with route_id/venue/chosen_by/fee/prepared_deploy, and the unavailable fallback with tried/supported_chains), plus the one-line example. Nothing an agent needs to invoke or interpret it 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 the schema already documents all 8 parameters including deployer's necessity and null-vs-zero for max_pool_fee_pct. The description restates some of this but adds little parameter-level meaning 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 states a specific verb+resource ('choose a launch venue', 'launch a token') and enumerates the venues covered (Clanker v4, Bankr, Virtuals, Zora). It explicitly distinguishes itself from the nearest siblings (route_swap, swap, route_lp, create_agent), so an agent can tell it apart without opening any 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?

Uses explicit USE WHEN / NOT FOR structure, naming each alternative tool and the condition that selects it (swap → route_swap, LP → route_lp, launch-prep repo → create_agent). Boundaries are 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?

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description adds substantial behavioral context beyond them: the recommendation-vs-fact rule, the deliberate omission of impermanent loss surfaced as an explicit null, the fee-revenue proxy definition, the 'never scaled up' window rule, the null-means-unknown (not zero) semantics, v4 null-with-reason handling, and a non-custodial statement. This is rich disclosure beyond structured fields.

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

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

Front-loaded with USE WHEN / NOT FOR and organized under clear headers (RULE, THE PICK, COVERAGE, NON-CUSTODIAL, RETURNS). Given the tool's complexity the length is mostly justified, but the emphatic guardrail phrasing ('never... never...') and the long field enumeration in the RETURNS block are more verbose 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?

No output schema exists, so the description must carry the return contract, and it does thoroughly: the full pools[] field list, the chosen object with chosen_by, the unranked case, the latest_week/note fallback, and the unavailable shape. Combined with the pick rule and coverage limits, an agent has everything needed to call and interpret this complex 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 100%, so both required params (pair, chain) and the response_format enum are already fully documented, including the 'unknown, never empty' semantics for unsupported chains/pairs. The description only restates coverage constraints and adds a one-line example, so the schema does the heavy lifting — 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?

States a specific verb and resource: comparing Uniswap v3 pools/fee tiers for a pair so an agent can decide where to provide liquidity. It explicitly distinguishes itself from onchain_agent_route_swap, onchain_agent_swap and onchain_agent_route_launch, so the agent can route correctly without opening any 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?

Opens with an explicit 'USE WHEN' condition (deciding which pool/fee tier to LP, wanting observed readings not an opinion) and a 'NOT FOR' clause naming the three alternative tools for swaps and launches. When-to-use, when-not, and alternatives are all present.

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/non-destructive/idempotent, and the description adds substantial non-obvious behavior: it never signs, holds, moves or broadcasts funds; it returns calldata the caller may sign; a failed, reverted or unsigned trade pays nothing; the fee schedule (3/15/75/25 bps) and where in the transaction it is taken; and that a route is a recommendation, not an assurance. This is well beyond what annotations 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?

Well-structured and front-loaded with USE WHEN / NOT FOR / RULE ENFORCED / NON-CUSTODIAL / THE FEE / RETURNS headings, and the RETURNS section legitimately substitutes for a missing output schema. However, the sentences about token-launch creator LP shares and Sato OS perp builder fees are tangential to this specific tool and could be trimmed.

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 fully documents the return shape (route, quote, fee fields, referral, chosen_by, unavailable fallback) and the non-custodial contract, plus an example invocation. For an 8-param routing tool with meaningful behavioral nuance, nothing an agent needs to call it correctly appears to be 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 the schema already documents all 8 parameters thoroughly (including referral fallbacks and taker semantics). The description adds little parameter-level meaning beyond a concrete example using chain/token_in/token_out/amount, 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 — obtain a swap QUOTE with the venue chosen by liveness, verification and price — and explicitly distinguishes itself from onchain_agent_swap, onchain_agent_route_launch and onchain_agent_route_lp by name. An agent can identify this tool without opening the 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' clause plus a 'NOT FOR' clause naming three sibling alternatives and the conditions that select each. Nothing about when to pick this vs. a verdict-checked swap 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 readOnly/idempotent annotations, the description discloses that nothing is generated, that the tool is non-custodial (no keys, signing, deploying), and that untrusted install lines are surfaced via quarantined_installs rather than invented. It also documents compatibility shims (files empty, bytes 0, include_zip ignored, mode plan_only) that annotations alone would not 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?

It is front-loaded with the USE WHEN/NOT FOR routing that an agent needs first, and most sentences carry distinct information. However, the return payload is documented twice (a prose RETURNS section and a JSON RETURNS block) and the 'every door downloads the same repo' line is filler, so it falls short of 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?

With no output schema and six parameters on a fairly complex tool, the description fully enumerates the return shape (plan fields, env_names, quarantined_installs, create pointer or null), the non-custodial guarantee, and the compatibility fields. An agent has everything needed to call it and interpret the response.

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, but the description adds meaning by explaining that include_zip is accepted purely for backward compatibility and ignored, and that mode is fixed at plan_only. It doesn't add syntax guidance for goal/chain/budget beyond what the schema already says, keeping it to a 4.

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 (builds the plan) and resource (a plan plus a create pointer to the repo generator), and explicitly positions it against onchain_agent_build_plan and onchain_agent_create_agent. An agent can tell it apart from the full-plan sibling and the repo-generation sibling without opening any 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?

It states a concrete USE WHEN condition ('a plan has been agreed and the next question is which repository to start from'), explicit NOT FOR cases with named alternatives for each, and clarifies that the repo itself must come from onchain_agent_create_agent. Nothing about routing 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 only cover the read-only/idempotent/no-destruction profile, and the description adds substantial context beyond that: a privacy disclosure (recipient, token, wallet, origin and amount are not stored; only chain is), 'nothing is signed or sent', and a definition of every verdict including the crucial caveat that 'go' is never a clearance and 'unknown' means no record either way.

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 USE WHEN / NOT FOR / WHAT IT READS / RULES / RETURNS headers, so an agent can skim. It is on the verbose side — the five numbered questions and the rules paragraph are long — but nearly every sentence carries operational meaning, so it stops short of padding.

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

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

No output schema exists, but the description inlines the full return shape (schema id, verdict enum, rule, reason, answers, limits, as_of, caveat) plus a worked example call. For a pre-payment safety check this is as complete as an agent needs to invoke and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine routing guidance: chain and recipient are the minimum, while token, origin and paying wallet are optional enrichments that widen the reading. It also explains the semantics of each optional field (what declaring an origin or comparing against the paying wallet buys you) rather than repeating schema text.

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 (scan/check) and a specific resource (a recipient address) with the exact trigger moment: 'USE WHEN an agent is about to pay or transfer to an address'. It also names the sibling it is not via 'NOT FOR checking a package, repo, token, endpoint or agent (use onchain_agent_preflight instead)', so an agent can route between the two 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?

Explicit when-to-use ('about to pay or transfer'), a concrete list of optional inputs that deepen the reading, and an explicit exclusion list naming the alternative tool. Both the positive and negative conditions are stated, leaving nothing 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 cover read-only/idempotent safety, yet the description adds substantial non-structured behavior: registry-first ordering with listings[] fallback, brands[] returned for brand-name queries but excluded from total, and the trust caveat that registration is self-reported with verification_status distinguishing Self-Reported from Verified/Audited. It also warns that an empty result says nothing about ERC-8004 agents — a critical failure-mode disclosure.

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

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

Front-loaded with USE WHEN / NOT FOR / RETURNS blocks, which is an efficient structure for a complex tool. It runs long and includes some lines that restate structured data ('Read-only.' repeats readOnlyHint), but the density of genuinely new information justifies most of the length.

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

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

No output schema exists, yet the description enumerates the return shape (total, agents[] fields) and the secondary envelopes (listings[], brands[]). Combined with the scope and trust-rule disclosures, an agent has everything needed to call this correctly and interpret an empty result.

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

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

Schema coverage is 100% so baseline is 3, but the description adds real meaning beyond it: 'query' is described as also triggering brands[] when it names a brand, and x402_only is exemplified in a concrete call ({ chain: "Base", x402_only: true }). It stops short of explaining response_format's structuredContent behavior, which the schema already covers.

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 ('search live registered agents you can hire or pay') and immediately disambiguates from what it is not — a build tool, a passport lookup, or a router. The agent can tell this apart from search_resources and get_agent_passport without opening any 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 when-to-use ('need a RUNNING agent to work with, hire or pay'), explicit when-not with three named sibling alternatives and their conditions, plus a boundary note directing ERC-8004 lookups to onchain_agent_get_agent_economy. This is a complete routing map.

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

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

Annotations already cover read-only, idempotent, non-destructive, open-world behavior, but the description adds substantial context beyond them: the evidence rule (counts only rows recorded against the exact digest, 'not_checked' means none exist), the scope disclaimer that a result is not a safety/security/returns claim, and the guarantee that no signed download URL is ever returned. These are real operational constraints an agent cannot derive from structured fields.

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

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

Long but dense and front-loaded: USE WHEN, NOT FOR, RETURNS, RULE ENFORCED, Example. Every section contributes distinct, non-redundant information, and the routing condition is placed ahead of the detail.

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

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

No output schema exists, so the description carries the burden and does so by enumerating the returned listing fields (slug, version.digest, evidence_freshness, fork_permitted, acquisition_modes, superseded_by, etc.) and explaining superseded_by semantics. Combined with the enforced-evidence rule, an agent has everything needed to call and interpret the result.

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

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

Schema description coverage is 83%, so the schema already documents query, cursor, recipe, and license. The description adds only a small example invocation ({ query: 'treasury', limit: 10 }) and restates the cursor/next_cursor linkage already present in the schema; it does not clarify the recipe/license filter semantics further. 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 and resource: searches Sato Hub's published agent packages, each described as a public view of one sealed, immutable version. It explicitly distinguishes itself from onchain_agent_search_resources, onchain_agent_search_agents, and onchain_agent_create_agent, so an agent can route correctly without opening sibling 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?

Opens with an explicit USE WHEN clause (ready-made package to download or fork rather than assemble) and a NOT FOR clause naming three alternatives with the conditions that select them (frameworks/MCP servers, hiring/running agents, generating a fresh repo). Nothing about 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 declare read-only, idempotent, open-world, non-destructive behavior, but the description adds substantial context beyond that: deprecated resources are never returned, closed-vocabulary filters are refused with the valid list rather than silently empty, the directory is daily-rebuilt and evidence-scored, and the no-argument default returns a compact overview with counts. It even notes that min_observed_success is a share of the provider's checks, not uptime.

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 USE WHEN / NOT FOR and organized under clear section headings, which suits a 26-parameter tool. It is long, and the FILTERS section partly repeats the input schema, but the length is largely earned by the tool's complexity and the examples are compact.

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 26 optional parameters, no output schema, and full schema coverage, the description is complete: it outlines the return shape, explains pagination and defaulting behavior, covers special query semantics, and warns about the closed-vocabulary refusal. Nothing essential for correct invocation appears 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 the baseline is 3. The description still adds meaning beyond the schema: it documents the closed-vocabulary refusal behavior, the special 'starter'/'template' query semantics, the no-argument compact-overview behavior, and concrete natural-language-to-parameter examples. Some filter lists restate the schema, but the added behavioral nuance justifies a 4.

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

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

The description opens with a specific verb+resource ('look up crypto-agent tooling') and enumerates the dimensions by which it can be searched. It also explicitly distinguishes this tool from five sibling search/retrieval tools in the NOT FOR section, so an agent can tell it apart without opening any 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?

The USE WHEN / NOT FOR structure gives explicit when-to-use and when-not-to-use guidance. Each excluded case names the correct alternative tool (onchain_agent_recommend_stack, search_agents, search_listings, search_skills, get_resource), leaving no routing ambiguity.

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

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

Annotations already cover readOnly/idempotent/non-destructive/openWorld, and the description still adds real behavioral context: a disclosure is a description not a safety verdict, no flags is not a clearance, the registry scan is attributed to the registry, and an unmatched slug returns empty with a note about what the slug actually is. That is genuine value beyond the structured fields.

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

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

Front-loaded with USE WHEN / NOT FOR / RETURNS before caveats and worked examples, so the important routing information arrives first. It is on the long side and the RETURNS block plus caveats could be trimmed slightly, but nearly every sentence carries selection or invocation signal.

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 supplies the full JSON return shape, the meaning of each disclosure flag class, the citation requirement, and three worked query examples. For a six-parameter search tool this leaves nothing an agent needs in order to 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 coverage is already 83% and documents flag, slug, query, registry and response_format, so the baseline is 3. The description goes further by explaining slug's directory-listing semantics and the empty-result/fallback behavior, and by tying query to hosts contacted, which the schema does not.

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

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

States a specific verb and resource (searching crypto-relevant agent skills) with the exact scope: static disclosure flags for skills about to be installed. It explicitly distinguishes itself from onchain_agent_search_resources, onchain_agent_check_install, and onchain_agent_preflight by name, so an agent can route without opening a 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?

Leads with an explicit USE WHEN trigger (about to install a skill and need to know what it touches) and a NOT FOR clause that names three alternative tools and the condition selecting each. Nothing about when to pick this over its siblings is left to inference.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), but the description adds substantial context beyond them: the 5-writes/hour rate limit, the shared triage/apply path, the public-evidence probing and list/hold/decline outcomes, the single-email behavior, that a hold is silent, and that submission is not verification. This is exactly the kind of operational detail 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?

Front-loads the routing decision, then layers WRITES / WHAT HAPPENS NEXT / DEDUPE / LIMIT / RETURNS as scannable labeled blocks, so it is easy to parse. It is long, but for a mutation with this many side effects and constraints the length is largely earned; only marginal trimming would help.

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 (4 required), no output schema, and a mutation on an open world, the description carries the load well: it documents the write path, dedupe behavior, rate limit, notification semantics, and even enumerates the JSON return shape and a sample call. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by explaining that the website host and repository act as dedupe keys checked against the live directory and pending submissions, and by clarifying the consequence of supplying contact_email (exactly one email, only on listing) — semantics not stated in the schema. It still omits field-level guidance that the schema covers.

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 ('files the same row the /submit form files') and explicitly frames it as submitting a project to the directory. It distinguishes the tool from three siblings by name — onchain_agent_search_resources, onchain_agent_register_agent, and the claim flow — so an agent can route without opening any 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?

The 'USE WHEN' / 'NOT FOR' structure is explicit: it states the triggering condition (a project not in the directory that the agent wants considered) and three excluded cases, each with the correct alternative tool or flow. 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 only give the generic safety flags (readOnly=false, destructive=false, openWorld=true, idempotent=false), while the description supplies the real behavioral context: non-custodial, never signs or broadcasts, build-tx writes a receipt row, unknown targets refuse by default, refusals are not errors and are not retryable, and fee disclosure happens before signing. This is far beyond repeating structured fields and is consistent with the annotations.

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

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

It is long, but it is front-loaded with USE WHEN / NOT FOR / modes and uses capitalized headers to make it scannable rather than a wall of prose. Some material (the RETURNS block) is verbose enough to feel like smuggling in an output schema, though that block does real work given no output schema exists.

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 15-parameter, mutating, open-world tool with no output schema, the description covers the full lifecycle: inputs, gate/verdict behavior, refusal semantics, fee disclosure, cross-chain lane, receipt side effect, and a documented return shape including the error path (`unavailable`/`fee_side_unavailable`). An agent has everything needed to call it and interpret the result.

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

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

Schema description coverage is 100%, so the baseline is 3, and most parameter meaning (venue pinning, recipient semantics, recipient_owner/RCPT5, referral rules, slippage caps) is already in the schema text. The description's added value at the parameter level is marginal — the fee-side/`sato_fee_token` logic and the native-coin 0x000…0 convention are useful, but they describe output fields more than input parameters.

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

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

The title and opening sentence state a specific verb+resource chain (quote a swap, check against policy, produce an unsigned tx) and the two modes are named and distinguished. It also explicitly separates itself from onchain_agent_route_swap, route_launch and route_lp, so an agent can pick it out of a large sibling list.

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

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

A 'USE WHEN' clause gives the triggering condition, a 'NOT FOR' clause names three alternatives with the exact condition that selects each, and the mode semantics (recommend vs build-tx) state when a transaction will and will not appear. Nothing about 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 only declare the safety profile (readOnlyHint=false, idempotentHint=true, etc.), but the description adds substantial behavior: it writes one subscription row, goes through the same validation/normalisation/rate-limit path as the public form, re-checks daily, mails ONLY on verdict change, never mails transitions into unknown, is idempotent on re-subscribe, and unsubscribing answers identically regardless of prior state. It also discloses retention (normalised target, address, HMAC, baseline verdict; no IP or name). This is well beyond what the annotations cover.

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 USE WHEN/NOT FOR and organized into labeled blocks that each carry distinct information. It is dense and slightly long, but nearly every sentence adds an operational fact rather than restating structured data.

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 supplies a RETURNS field list and a concrete example call. Combined with full disclosure of lifecycle, idempotency, and storage, an agent has everything needed to invoke 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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema, notably the wallet-specific behavior ('get told when Sato Scan sees address poisoning aimed at that wallet') and reinforces unsubscribe idempotency. It does not explain the response_format parameter, but that is trivial and schema-documented.

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 (watch/subscribe) and resource (repo, package, endpoint, agent, wallet) and explicitly distinguishes itself from onchain_agent_preflight and onchain_agent_recent_changes. An agent can identify this as the persistent-subscription tool versus the one-off check tool 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?

It has an explicit 'USE WHEN' block and a 'NOT FOR' block naming two alternatives with the condition that selects each. Nothing about when to route here versus a sibling 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/idempotent/non-destructive, but the description adds real behavioral context: max 10 results, best-first ranking, single query string, empty-array-on-no-match with no padding plus a scope_note, and the cite-the-url convention. It also describes the handoff path (pass an id to fetch) which 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?

Front-loads the trigger, then segments NOT-FOR, RETURNS and Examples, so an agent can scan to the needed section. Dense but nearly every clause carries routing or return-shape information; the parenthetical list of index contents is slightly over-stuffed.

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 search tool this is fully covered: what it searches, what it excludes, result count and ordering, empty-result semantics, and how to continue via fetch. Output schema exists, so restating the return shape is a bonus rather than a 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 coverage is 100% and the schema already explains the query field, including the 200-character matching limit, so the baseline is 3. The four example queries add concrete guidance on phrasing (project name, chain, standard, natural-language question) that meaningfully exceeds the schema's generic wording.

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 — a single free-text query box over the Sato Hub index — and enumerates exactly what the index covers (frameworks, MCP servers, wallets, x402/stablecoin rails, data tools, wiki, agent-economy numbers). It also draws the negative boundary (not token prices/trading/advice), which no sibling tool name implies on its own.

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?

Opens with an explicit 'USE WHEN' trigger and then names two alternatives with the conditions that select them: onchain_agent_search_resources for filtered/paginated directory queries, and onchain_agent_search_agents for registered agents. Both when-to-use and when-not-to-use are covered with named fallbacks.

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