Sato Hub: Onchain Agents

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

Annotations (readOnlyHint, idempotentHint, destructiveHint=false) are reinforced and far exceeded: the description discloses the 'OURS, LABELLED' self-promotion rule for the execution block, non-custodial guarantees (never holds keys, signs, deploys, or moves funds), the honesty rules (null is unknown and never zero, a matched-nothing scan is reported as matching nothing), and that Sato Score is not a security review. This is exactly the behavioral context an agent needs that structured fields cannot convey.

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

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

The description is well-organized with section headers (RULE ENFORCED, OURS LABELLED, SKILLS, NON-CUSTODIAL, SHAREABLE) and is front-loaded with the USE WHEN trigger. However, it is very long and contains redundancy, e.g., the non-custodial point and 'not a security review' qualifier are stated more than once. Length is largely earned by tool complexity, but tighter editing would improve it.

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 full Returns JSON structure, the exact share-url behavior with signature verification, the ethical disclosure rules for skills, and a concrete example input. For a tool this complex that composes many sub-tools, virtually nothing an agent needs to call it correctly and interpret its 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 baseline is 3. The description largely mirrors the schema on save/public (share_url, noindex, re-checked signature), chain (read from goal when omitted), and budget_usd (restated, does not filter stack). It adds an example goal and the Returns JSON shape, but little that the parameter descriptions themselves do not already state.

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 (build a plan from a plain-words goal) and a resource (onchain agent goal → actionable build plan). It differentiates from the 30 siblings by declaring it 'Composes the other tools into one answer,' which clearly positions it as the aggregate planning tool versus route_swap, preflight, recommend_stack, etc.

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

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

It opens with 'USE WHEN someone describes the onchain agent they want and needs a plan they can act on rather than advice,' giving clear when-to-use context and a partial exclusion ('rather than advice'). It does not explicitly name sibling alternatives or state when NOT to use it, so the exclusion guidance is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint and destructiveHint=false, and the description affirmatively confirms 'Read-only' while adding substantial behavioral context: the tool reads 'off the live records, never typed', enforces a mandatory caveat, and clarifies that the Sato Score is an openness/activity/verifiability grade, not a safety or quality rating. This is meaningful disclosure beyond the annotations.

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

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

The description is compact relative to the information it carries, and the purpose is front-loaded in the first sentence. Every section (context, rule, semantics, return shape, example) serves a purpose, though the return-shape field listing and the example could arguably be trimmed without loss.

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 explaining return values — and it does, specifying the exact JSON shape including a, b, rows, caveat, rules, comparison_page, and source. It also includes a mandatory-rule caveat and an example call. For a tool of this complexity, nothing needed to invoke 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 all three parameters with examples and the response_format enum. The description adds a concrete example invocation ({ a: 'coinbase-agentkit', b: 'solana-agent-kit' }) which is mildly helpful, but does not materially extend the schema's parameter meaning — hence the 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?

The description opens with a specific verb-resource question — 'how do these two directory listings compare on the axes Sato Hub tracks for both?' — and lists the exact axes returned. This clearly distinguishes it from siblings like get_metrics or get_listing_history, which track a single listing over time rather than comparing two.

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

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

The description gives strong context on when this tool is appropriate: it answers a pairwise comparison question and returns the same table the /compare pages render. It also states what the tool cannot do — there is NO winner field and none can be derived — which functions as an explicit 'when not to use' rule, though it does not name sibling alternatives like search_agents or get_listing_history by name.

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

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

Beyond the annotations' readOnlyHint/idempotentHint, the description discloses important behaviors: it enforces a provenance rule (numbers never aggregated across venues/chains/stages), returns an error while unpublished, and requires the payload URL to be cited. This adds context about output integrity and answer format that the annotations do not provide.

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

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

The description is front-loaded with a one-sentence purpose, then gives the key behavioral rules, output shape, and a concrete example. It is more verbose than minimal but every section earns its place, especially the return-list since there is no output schema. The uppercase stylistic choices are mildly noisy but not wasteful.

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?

Since there is no output schema, the description compensates by enumerating the JSON return fields (slug, title, number, unit, stage, method, sample, lines, query, as_of, url, cite, rules) and giving an example call. It also covers unpublished-report behavior and read-only status, making the tool reasonably complete for independent invocation.

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

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

Schema description coverage is 100% and already explains the slug as a URL path segment and response_format as an enum with a default. The description adds a helpful example slug and reiterates the slug-shape URL, but it does not meaningfully elaborate on the parameters 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 verb-resource relationship: it answers where a published Sato Hub number comes from and returns one finding by slug. It gives clear distinctions from broad sibling tools like search_agents or get_metrics, focusing on provenance metadata for a single slug.

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

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

Usage is implied rather than explicit: the example and slug input set up the intended invocation, and the error-while-unpublished note gives a temporal constraint. However, there is no clear when-to-use-versus-alternatives guidance or named sibling exclusions, so an agent must infer when this tool is preferred over similar lookups.

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

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

Beyond the readOnlyHint annotation, the description adds substantial behavioral detail: the exact JSON return shape, the rule that 'null value means UNKNOWN, never zero,' the publishable threshold for low sample sizes, and venue-specific caveats like Solana upper bounds. This gives the agent the operational semantics it needs to interpret results safely.

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

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

The description is long but appropriately structured with sections for trigger, return shape, usage rules, and examples. The most important operational guidance is front-loaded, and every block adds information an agent needs to call the tool correctly.

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

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

Given the tool's complexity, the absence of an output schema, and rich annotations, the description is remarkably complete. It documents the return JSON structure, caveats, coverage boundaries, sourcing, and citation URL, so an agent has enough context to invoke and interpret the tool correctly.

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

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

Although schema coverage is 100%, the description adds valuable semantic context through examples: '{ chain: "Base" }', '{ venue: "erc8004", include_platforms: true }'. It also explains that include_platforms roughly doubles the response and that venue-level rows have no chain, going beyond the schema's field descriptions.

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

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

The description opens with a specific trigger ('USE WHEN asked how big the onchain agent economy actually is') and names the measured resources: registries, launchpads, payment rails, and account infrastructure. It clearly differentiates measured chain reads from deck/announcement figures, but it does not explicitly distinguish this tool from sibling tools like get_metrics or get_trend.

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

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

The description provides an explicit 'USE WHEN' condition and concrete examples mapping user intents to parameters. It also states coverage boundaries, e.g., 'Solana payment settlement is not covered by any row,' and warns against summing numbers. It stops short of naming alternative sibling tools or giving a when-not-to-use routing rule.

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 include readOnlyHint, idempotentHint, and destructiveHint=false, indicating a safe, read-only operation. The description adds context that payment metadata is self-configured and published for interoperability, not endorsement, and that it returns an error for unknown slugs. It does not contradict annotations, and adds value beyond them.

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

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

The description is concise and front-loaded with the usage context. It packs a lot of information (what it returns, when to use, alternative, error handling, example) into two sentences plus an example, without unnecessary words.

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

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

Given the tool's moderate complexity (2 params, no output schema), the description covers the key aspects: purpose, usage context, error conditions, and a note on payment metadata. It lacks a detailed explanation of the 'verification + liveness status' fields or the exact manifest structure, but the context is sufficient for an agent 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 both parameters are fully described in the schema, including the slug description and the response_format enum/default. The tool description reiterates the slug example and search hint, but adds little beyond the schema. With full schema coverage, baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: to look up the identity of a single registered agent by slug. It specifies the verb 'get', the resource 'agent passport', and the target 'one registered agent'. It distinguishes itself from the sibling tool onchain_agent_search_agents by noting that search is for finding slugs, while this tool retrieves the full manifest.

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

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

The description explicitly says 'USE WHEN you are about to work with, pay or depend on a registered agent', providing clear context. It also mentions using onchain_agent_search_agents to find slugs, and states error conditions for unknown slugs. This gives clear guidance on when to use this tool versus alternatives.

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

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

The description goes well beyond the annotations by explaining that additions are exact, removals are approximate, field-level diffs catch quiet edits, and the operation is read-only. It is weakened by an internal inconsistency: the return signature lists `changed`, while the coverage section describes `updated` as the field-level diff, which could confuse an agent.

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

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

The description is front-loaded with the 'USE WHEN' trigger and includes a concise return-shape block, coverage notes, and examples. It is dense but not bloated, though the 'COVERAGE (also stated in the response)' phrasing is slightly redundant with the return block.

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?

Because there is no output schema, the description rightly carries the burden of explaining return shape, field semantics, and example usage, and it does so thoroughly. Minor gaps remain around pagination/full_export semantics and the updated/changed naming inconsistency, but the tool is still safely callable.

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

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

The single `since` parameter is already fully documented by the schema with format, default, and clamping, so the baseline is 3. The description adds operational value by giving concrete example mappings and advising to store baseline_date as a cursor, which earns 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 states a clear purpose: fetch only catalog changes since a date for syncing a local copy, and distinguishes this from re-fetching the whole catalog. However, it does not explicitly differentiate itself from the similar sibling onchain_agent_recent_changes, so it falls short of full sibling separation.

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' clause openly identifies the intended scenario and the examples show concrete invocation patterns. It implies when not to use it ('rather than re-fetching the whole catalog') but does not name alternative tools or provide explicit exclusion conditions.

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?

Adds substantial behavior beyond the readOnly/idempotent annotations: explains deploy_status as a trust signal rather than a safety guarantee, notes that missing manifests return an error, and includes a safety warning about verifying keys and permissions. Also explicitly states 'Read-only.'

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

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

Front-loaded with the use trigger and organized into clear sections: use case, return shape, trust semantics, error behavior, and example. Slightly verbose but each sentence adds useful context without redundancy.

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

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

With no output schema, the description provides a detailed return shape, explains deploy_status semantics, warns about safety, and documents error conditions. This is enough for an agent to know what to expect and how to 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?

Input schema has 100% description coverage for both params, so the schema already carries the parameter documentation. The description adds an example for slug but does not meaningfully elaborate on response_format or go beyond what the schema provides. 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?

Description uses a specific verb+resource: returns the structured deploy manifest for one resource by slug, including install commands and runtime. It clearly differentiates itself from sibling tools by focusing on verified install/deploy information rather than general resource info, metrics, news, or wiki pages.

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?

Starts with 'USE WHEN you are about to write setup instructions or install something' which gives a clear trigger and context. It does not explicitly name alternatives or exclusion conditions, but the intended use case is strongly implied and distinguishable from sibling tools.

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

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

Annotations already declare the tool is read-only, idempotent, and open-world, and the description reinforces this with 'Read-only' and 'Absence of a record is unknown, not down.' It adds substantial non-obvious behavior: success_rate_pct is the share of Sato Hub's own checks (not uptime), daily rows are not returned, a maximum of 30 entries, and score_series gaps are left absent rather than filled. This goes well beyond annotation basics and clarifies edge 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?

The description is long but every section earns its place: the core question is front-loaded, the rule and edge cases are separated, and the example at the end anchors the parameter usage. Despite the length, it is well organized and does not repeat schema text verbatim, making it appropriately sized for the complexity.

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

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

With no output schema, the description compensates well by listing all return fields, bounding the window, and explaining the most error-prone semantics (success_rate_pct, absence, score_series gaps). The only notable gap is a minor inconsistency: the description says 'Returns (json)' while the schema's response_format defaults to 'markdown' and allows both formats; an agent could be unsure whether the default output is JSON or Markdown without reading the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enriches several parameters: it clarifies that days produces a bounded 30-day shape, and it explains score_days in detail—up to 365 days, absent days omitted, and movements labeled project or methodology. It does not add much for slug or response_format, but the added semantics justify a notch above baseline.

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

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

The description opens with a sharply framed question—'has this listing been answering Sato Hub's daily checks, and has its tool inventory moved?'—and then enumerates the exact data returned: observed record, tool-history changes, and Sato Score. This is a specific verb+resource that is semantically distinct from sibling tools like get_resource or get_metrics, which fetch general resource or metric data rather than this focused listing-history shape.

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

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

The description makes the tool's purpose and main optional behavior ('Pass score_days to add score_series') unmistakable, so an agent can infer when this tool is relevant. However, it never explicitly names alternatives or states when not to use this tool versus siblings such as get_changes or get_metrics, so the guidance stops short of giving exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, and the description reinforces this with 'Read-only.' Beyond annotations, it discloses the data source (Ethereum mainnet ERC-8004 registry), the inclusion rule for the token index (only directory-listed projects, never the whole category or aggregate market cap), and the exact return shape. This is substantial behavioral detail that helps an agent trust and interpret the result.

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

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

The description is well-structured with a front-loaded usage trigger, a compact explanation of what is included and excluded, and an inline return schema. It is slightly long but justified because there is no separate output schema in the definition and the exact semantics of the curated index need clarification.

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

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

Given the tool has no output schema, the description compensates by embedding the JSON return structure. It also explains what each number represents, how the agent count is sourced, and what the token index intentionally excludes. Combined with the annotation set, nothing critical is missing for an agent to decide whether and how to invoke 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%, and both parameters (token_limit, response_format) have clear inline descriptions, defaults, bounds, and enums. The description does not need to add parameter syntax, and it does not; it focuses output semantics instead, which is appropriate. Baseline 3 is the right level because the schema already carries the parameter meaning.

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

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

The description clearly identifies the tool's purpose: retrieving live ecosystem metrics, specifically the ERC-8004 registered-agent count and the curated Top Project Tokens index. It describes the resource and scope in enough detail to distinguish it from sibling tools like news, changes, or resource lookups, even though it does not name an alternative explicitly.

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

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

The description provides an explicit 'USE WHEN' condition: a current, citable figure is needed, and it draws a contrast with 'a number from an article of unknown age.' This gives clear context and a when-not-to-use signal, though it does not name an alternative sibling tool as the preferred replacement.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive, and the description reinforces 'Read-only' while adding meaningful behavioral detail: results are source-attributed, filtered to the agent economy, and paginated. It also discloses the exact JSON return shape including pagination fields such as total, count, offset, has_more, and next_offset.

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

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

The description is front-loaded with the trigger condition, followed by source scope, filtering options, pagination, return shape, and a compact example. Every sentence earns its place, and there is no redundant or filler content.

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

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

There is no output schema, but the description compensates by providing a full return-shape sketch and pagination semantics, so an agent can predict what the tool returns. Combined with fully documented parameters and safety annotations, nothing essential for selecting or invoking this read-only 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?

The input schema covers 100% of parameters with descriptions, enums, defaults, and bounds, so the description does not need to add much. The example and the mention of filtering/pagination are convenient, but they add no semantic content beyond what the schema already provides.

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

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

The description opens with a specific trigger ('asked what is new or what shipped recently in crypto AI agents') and names the resource: dated, source-attributed news/releases in the agent economy. It differentiates from siblings like get_changes/recent_changes by emphasizing GitHub releases, project announcements, and RSS rather than edit/change logs.

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

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

It explicitly states when to use the tool and gives selection criteria ('dated, source-attributed items rather than undated blog posts'). It also explains filtering by kind/chain and pagination, but it does not name sibling alternatives directly, so the when-not guidance is clear but not tool-to-tool.

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

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

Annotations already mark the tool read-only and idempotent; the description adds error behavior for unknown or Deprecated slugs and outlines the return payload (resource + recent_activity). The bare 'Returns (json)' is slightly ambiguous next to response_format's markdown default, but it does not contradict the annotations.

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

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

The description is front-loaded with the when-to-use trigger, followed by return shape, error behavior, and an example. It is compact, though 'Read-only' duplicates the annotation and 'Returns (json)' could be phrased more carefully.

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

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

For a simple single-record lookup with no output schema, it covers purpose, prerequisite search step, return payload shape, error conditions, and safety behavior. An agent has enough information to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so slug, response_format, and include_activity are already documented with defaults and enums. The description adds only a concrete slug example and restates that activity includes releases/posts, which is marginal 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 first sentence states a specific use case: judging a single project (open source, maintenance, authors, supported features). 'Returns the full record by slug' names the resource and key, and it explicitly points to onchain_agent_search_resources for slug discovery, distinguishing it from the search sibling.

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

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

'USE WHEN you need to judge one specific project' gives a clear trigger, and 'Find the slug with onchain_agent_search_resources first' provides the prerequisite and named alternative. It does not enumerate when-not cases for the other get_* siblings, but the single-project scope makes those exclusions reasonably inferable.

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, openWorldHint, idempotentHint, and destructiveHint false, so the bar is lower. The description adds substantive behavioral context: the score is recomputed daily, self-reported claims earn nothing, the payload itself disclaims being a safety/security/quality/returns grade, and the tool is read-only. It also states exactly what the returned payload contains.

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

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

The description is dense but well-structured into USE WHEN, RULE ENFORCED, and Returns sections, with the most important usage guidance front-loaded. Every sentence carries substantive information, from the trigger condition to the payload fields to the citation requirement. The length is justified by the complexity of the methodology being documented.

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?

Because there is no output schema, the description must carry the return contract, and it does: it lists the JSON fields (name, scale, components with key/label/max/measures, tiers, provisional, not_in_score, computed, reproduce, dispute, caveat, url). It also covers exclusions, computation cadence, reproducibility, and dispute routing. For a one-parameter read-only tool, nothing an agent needs to select and invoke 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%, and the single response_format parameter is fully documented with an enum and default, so the baseline is 3. The description adds no parameter-specific guidance, which is acceptable at this coverage level. The 'Returns (json)' line describes the payload shape rather than the response_format option, so it neither elevates nor significantly undermines 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 opens with a specific trigger ('USE WHEN you are about to describe, apply or compare the Sato Score') and names the exact resource, the Sato Score methodology. It further distinguishes itself by enumerating the six components, tier cutoffs, provisional meaning, exclusions, computation, and dispute path — far more specific than the sibling info tools.

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

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

It gives explicit use conditions: when describing, applying, or comparing the Sato Score, or when asked how to tell whether a project is real, maintained, or open. It also states what the score is not (safety, security, quality, legitimacy, returns) and requires citing the URL. It does not name sibling alternatives, but the trigger is clear enough that an agent would not confuse it with get_metrics or explain_number.

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

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

The annotations already declare read-only, idempotent, open-world, and non-destructive behavior, and the description complements them with rich normative behavior: points are never summed across venues/chains/stages, the tool actively refuses blended chains, null means UNKNOWN not zero, weekly points are the citable ones, daily points never become a headline, and raw rows are not returned. This is exactly the kind of beyond-schema transparency that helps an agent predict side effects and data semantics correctly.

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

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

The text is long but purposeful: a one-sentence purpose statement comes first, then a clearly labeled RULE block, then a compact return-shape summary and three illustrative examples. Every major section earns its place because this is a seven-parameter tool with a non-trivial return shape. The all-caps 'ANSWERS ONE QUESTION' and 'RULE ENFORCED' are slightly aggressive, but they front-load the message without becoming filler.

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

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

Given there is no output schema, the description carefully documents the entire return envelope through a sample shape: venue, chain, stage, grain, unit, points with nested fields, direction_first_to_last, known_points, rules, as_of, and source. It also covers the edge semantics around chain omission and null/UNKNOWN. For a tool with this parameter complexity and no output schema, the description uniquely supplies the missing pieces an agent needs 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 description coverage is 100%, so the baseline is already strong, but the description adds meaningful resolver examples that map user phrasing to concrete parameter sets, e.g., 'are ERC-8004 registrations on Base growing' -> { venue: 'erc8004', chain: 'Base', stage: 'registered' }. It also reinforces default and range semantics ('at most 30 points, default 8') and chain refusal when omitted, which goes beyond simply restating the schema. It does not revisit the 'response_format' option or the full 'movers' semantics, so it is not 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 opens with a specific question ('is this measurement going up or down?') and then names the resource and scope: Sato Hub's weekly/daily chain reads for ONE venue, ONE chain, ONE stage. It clearly distinguishes the tool from broader directory tools by emphasizing that venues, chains, and stages are never blended. A small deduction: it does not reference sibling tool names even though that would sharpen differentiation.

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

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

The description gives concrete guidance: use 'stage' mode for a single series, 'movers' for directory movement, choose weekly when you need a citable number, and prefer daily only for trend context. It also explains when to omit or supply a chain, including that the tool will tell you which chains exist if you omit one. It stops short of explicitly contrasting with alternative sibling tools like get_metrics or get_listing_history, but the scoping rules prevent many confusions.

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 behavior, and the description adds useful behavioral details: it returns a full page object, returns an error for unknown slugs, and documents the content structure. There is minor ambiguity around the response_format default (markdown) versus the description's 'Returns (json)' phrasing, but no direct contradiction with annotations.

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

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

The description is front-loaded with the usage trigger and stays reasonably compact while covering purpose, return structure, slug discovery, error behavior, and an example. Minor redundancy exists ('Read-only' repeats the annotation, and the 'Returns (json)' line could be clearer), but overall every section earns its place.

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

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

For a simple read-only wiki lookup with two parameters and no output schema, the description is largely complete: it explains what the page contains, how to find slugs, what errors to expect, and the response format option. The small ambiguity about markdown versus JSON output prevents a perfect score.

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 both parameters and the default. The description adds an example slug and notes error behavior for unknown slugs, which adds some semantics, but it does not substantially expand on what the schema already provides.

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

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

The description clearly states the tool's purpose with a specific verb ('explain') and resource ('crypto-agent concept'), lists concrete examples like x402 and ERC-8004, and enumerates the returned wiki page sections. It also distinguishes itself from sibling tools by directing users to onchain_agent_list_wiki_pages for finding 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?

The description includes explicit 'USE WHEN' triggers and tells users to use onchain_agent_list_wiki_pages to find slugs. It could be stronger in naming sibling alternatives like get_resource or search_agents, but it provides enough context for an agent to select this tool over the list/search 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 cover readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds value by specifying ordering ('most populated first') and the return JSON structure ({ total, categories: [{ name, count }] }). It also reinforces the read-only nature. No contradiction.

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

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

The description is compact and front-loaded with 'USE WHEN', immediately conveying the primary purpose. Each sentence serves a distinct function: usage trigger, listing behavior, output format, and read-only note. No filler.

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

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

For a simple tool with one optional parameter and no output schema, the description covers usage, return format, ordering, and safety (read-only). The annotations cover idempotency and openness. Nothing essential is missing for an agent 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% for the single parameter (response_format) with a clear description and enum. The tool description does not mention this parameter, so it adds nothing beyond the schema. Per calibration, baseline 3 applies.

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

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

The description clearly states the verb (lists), resource (resource categories), and provides output structure (counts, most populated first). It explicitly ties to a sibling (onchain_agent_search_resources) for pre-filtering, distinguishing it from other listing tools like list_chains.

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

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

Provides an explicit trigger condition: 'USE WHEN you need the valid category values before filtering onchain_agent_search_resources.' Also gives a secondary use case (understanding landscape division). It doesn't explicitly state when not to use it or name alternative tools, but the context is clear and actionable.

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, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral nuance: it orders spotlight chains first and filters out chains with only announcements. It also states 'Read-only' consistent with the annotation, and the return structure is disclosed, so no contradictions. Slightly more detail could be given on how counts are computed, but it is adequate.

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

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

The description is compact yet dense, front-loading usage guidance and then providing purpose, output format, and safety in a logical order. Every sentence adds necessary information with no redundancy or fluff.

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

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

For a tool with zero required parameters and one optional, the description covers all essentials: when to use, what it returns (including structure), the ordering behavior, and the read-only nature. There is no output schema, so the explicit return format is critical and provided. Nothing an agent needs to invoke 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 single parameter response_format is fully documented in the schema (100% coverage) with enum and description. The description adds value by showing the exact JSON output structure, which is particularly useful when response_format is set to 'json'. This goes beyond the schema's generic format explanation.

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

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

The description clearly states the tool lists every blockchain in the directory with resource counts, and explicitly distinguishes it from onchain_agent_search_resources by framing it as a prerequisite step. The verb 'list' plus the resource 'chains' makes the purpose unambiguous.

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

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

It opens with 'USE WHEN' and gives two concrete triggers: before filtering search_resources, or to identify chains with real tooling vs announcements. This directly guides the agent on when to select this tool over siblings like search_resources.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description reinforces this with 'Read-only.' It goes further by disclosing the return structure, '{ total, pages: [...] }', which is valuable because no output schema exists. It does not discuss potential pagination or result limits, but the core behavior is transparent.

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

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

Every sentence earns its place: a 'USE WHEN' guide, a concise list of returned fields, the return shape, and a read-only flag. It is compact, front-loaded, and free of filler or redundant restatements of the name or title.

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 zero-required-parameter read-only list tool, the description covers the main agent needs: when to invoke it, what fields come back, and the return envelope. It does not specify pagination or maximum result size, but the absence of an output schema is compensated by the explicit '{ total, pages: [...] }' shape.

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 only parameter, response_format, is fully documented in the schema with an enum, a default, and a clear description, so schema coverage is 100%. The tool description adds no additional parameter-level meaning beyond referencing 'json' in the return shape, which matches the baseline expectation.

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

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

Description uses a specific verb and resource: 'Lists every Onchain Agent wiki page (slug, title, keyword, summary, last_updated)'. It also explicitly frames the tool as the lookup step before onchain_agent_get_wiki_page, clearly distinguishing it from that sibling.

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

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

The description opens with 'USE WHEN you need the slug... before calling onchain_agent_get_wiki_page, or want to see which concepts have a sourced page you can cite.' This gives concrete invocation conditions and names the related tool, leaving little ambiguity about when this list tool is appropriate.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), yet the description adds substantial behavior: the 8 s single live handshake for unlisted endpoints, that unknown means 'no record held' rather than 'bad', permanently-null fields with reasons, no scraping/no execution, and evidence attribution per field. This is far beyond what the structured 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?

The USE WHEN trigger and the lane breakdown are front-loaded, and each paragraph maps to a target kind. It is on the long side and includes some asides (e.g. the locker/pool-depth remark) that inform calibration more than invocation, costing a point on tightness.

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 contract: it enumerates verdict, rule, target, evidence fields with source_field and checked_at, caveat, and the lane-specific token?/skill? reports. Combined with the rule-enforcement and null-handling notes, 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%, so the baseline is 3, but the description adds cross-parameter semantics the schema does not: 'Pass exactly one of repo, package, endpoint, agent or token', the token-requires-chain dependency, and the EVM-only restriction for the chain param. That raises it above baseline.

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

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

The first sentence names a specific verb (check/preflight) and enumerates the exact target kinds (repo, package, endpoint, agent, token, skill), and the lane descriptions spell out what is actually verified in each. This is clearly distinguishable from siblings like search_skills or 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?

'USE WHEN you are about to install a package, clone a repo, connect to an MCP endpoint, pay an agent, or trade a token' gives explicit triggering conditions, and 'Pass exactly one of...' constrains invocation. It also states what the verdict is NOT (not a security review, not a quality judgment), which functions as when-not guidance. No sibling alternative is named, which keeps it below a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds significant behavioral context beyond that: it explains that events are derived from the daily snapshot time-series plus the change-event log, suppresses passive drift, returns a specific JSON shape with tone values, and explicitly states 'Read-only.' It also reveals that results are high-signal and dated, which informs agent expectations about data granularity. No contradiction with annotations.

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

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

The description is front-loaded with the trigger phrase 'USE WHEN', then logically flows into usage instructions, event enumeration, data source, filtering, return format, and example. Every sentence earns its place; no fluff. It is about 140 words and covers necessary semantic ground without redundancy. The example at the end is an efficient way to illustrate parameter combinations.

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

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

For a read-only tool with 4 optional parameters, no required fields, and no output schema, the description is remarkably complete. It states the output JSON structure (scope, total, changes fields) and describes the tone field. It explains the filtering behavior (high-signal only) and the source data. The example shows valid usage. An agent could invoke this tool correctly without ever opening the schema. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so all four parameters are documented in the schema. The description adds value by providing usage examples ({ days: 7 } and { slug: 'coinbase-agentkit' }) and clarifying the slug omission behavior (site-wide feed vs one resource's history), which the schema only states terse. It does not repeat parameter details but enriches the reader's understanding of how the parameters combine. This is above the baseline of 3 for full schema coverage.

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

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

The description states a specific purpose: retrieving dated, attributable changes across crypto-agent tooling, either site-wide or for a single resource. It distinguishes from a 'current snapshot' and enumerates event types (status flips, verification grants, Sato Score tier moves, liveness, releases, field enrichment), making the tool's role instantaneously clear and distinguishable from siblings like onchain_agent_get_changes or onchain_agent_get_listing_history.

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

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

The description opens with 'USE WHEN asked what has changed recently...' and gives explicit instructions on omitting slug for the site-wide feed vs passing slug for one resource's history. It also clarifies that 'high-signal only' means passive score/liveness drift is suppressed, which guides the agent on what to expect. However, it does not explicitly name alternative tools or state 'do not use when...' — the differentiation from a current snapshot is implicit, not explicit. This is strong context but slightly short of naming the negative case.

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

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

Beyond the read-only and idempotent annotations, the description discloses that ranking reflects openness/activity/verifiability and explicitly disclaims any safety, quality, or returns judgment. It also documents the 'honest gaps' behavior when no strong directory match exists, adding real behavioral context.

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

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

The description is front-loaded with the use trigger, then compactly covers output composition, per-pick fields, ranking caveats, and an example. Every sentence contributes information without 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?

With no output schema present, the description takes on the burden of describing return values and does so concretely: trust-ranked stack, slot buckets, Sato Score, liveness, deploy-spec status, and gaps. The example and annotations complete the picture for an agent deciding whether to call it and what to expect.

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 description does not need to re-document parameters. The added example with goal and chain illustrates parameter usage, but most parameter meaning is already carried by the schema.

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

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

The description states a specific action and resource: turning a plain-language goal into a trust-ranked stack of directory resources bucketed into slots. This clearly distinguishes it from sibling get/search tools, which fetch or search individual resources rather than assembling a build stack.

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

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

The description opens with an explicit 'USE WHEN' trigger: someone describes an agent they want to build and needs concrete components rather than general advice. It does not name sibling alternatives like onchain_agent_search_resources, but the selection context is clear and actionable.

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

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

The description goes well beyond annotations: it discloses the two-step challenge flow, the 15-minute challenge validity, the 5-write-calls-per-hour rate limit, the PENDING state for unsigned registrations, the Self-Reported verification_status that no input can change, the single live probe and on-chain lookup, and the fact that declared standards are claims not approvals. This is rich behavioral context that annotations (readOnlyHint=false, destructiveHint=false) do not provide.

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

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

The description is long but every section earns its place: USE WHEN, TWO STEPS, WITHOUT A SIGNATURE, WHAT THE SIGNATURE PROVES, LIMIT, Returns, Example. It is front-loaded with the most important usage guidance and uses clear section headers. It could be slightly tighter, but the density of critical behavioral information justifies 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?

For a 14-parameter, two-step registration tool with no output schema, the description is remarkably complete. It covers the call sequence, the challenge format (EIP-191 personal_sign), the rate limit, the pending path, the verification semantics, and the return shape. An agent has everything it needs to call this tool correctly without opening the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the two-step flow: name and wallet_address are used in the first call to get the challenge, and wallet_signature plus signed_at are used in the second call to issue. It also clarifies that contact_email is required on the unsigned path and that agent_type, description, and chains_supported are required to register. This adds orchestration-level semantics the schema alone doesn't convey.

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

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

The description states a specific verb and resource: register an Agent Passport (self-issue with a wallet signature), and clearly distinguishes it from siblings like onchain_agent_get_agent_passport (read) and onchain_agent_submit_project (different submission flow). It also explains the two-step challenge/signature flow, which makes the tool's purpose unmistakable.

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

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

The description explicitly says USE WHEN an agent wants a public, machine-readable identity, and explains the two-step call pattern: first call without signature to get the challenge, second call with signature to issue. It also states when the unsigned path applies (PENDING for human review, contact_email required) and notes the EVM-only signature limitation. This is strong when-to-use guidance with clear alternatives 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 cover the safety profile (readOnly, idempotent, non-destructive), but the description adds substantial non-obvious behavior: top-3 get one live MCP handshake, a probe proves only one answered call, ERC-8004 registration proves a claim not function, null feedback ranks below zero, and no job-outcome data exists. It also discloses a real coverage gap (keyless ERC-8004 enumeration is not callable). This is exactly the extra context annotations cannot supply.

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?

Labeled sections (USE WHEN, RULE ENFORCED, COVERAGE, Returns, Example) front-load the essential routing decision and are dense with signal. Some sentences restate the same caveat twice (declared vs. working service) and the whole block is long, so it is efficient but not 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?

For a no-output-schema tool, the description spells out the return shape including the unknown branch, candidates_considered, probed and coverage, and states the semantic caveats an agent needs to interpret the result. Nothing needed to call or interpret 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?

Schema description coverage is 100% and the schema fields are already annotated with nuance (chain filters the passport pool, requires_mcp means declared-only). The description adds only a single example call, so it does not meaningfully extend parameter meaning beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Choose an agent for a task, with the pick explained') plus the signal basis of the choice (registration, service, feedback, liveness). An agent can identify this as the routing/pick tool. It never names the nearest siblings (search_agents, recommend_stack, route_swap) to draw the boundary explicitly, so it falls short of a 5.

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

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

'USE WHEN an agent needs another agent for a task and wants the pick explained' gives clear triggering context, and it states the fallback rule ('when nothing qualifies the answer is unknown ... never a low-confidence pick'). No explicit when-not or named alternative tool is given, so 4 rather than 5.

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

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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: it never signs, holds keys, or moves funds; it returns a prepared clanker-sdk v4 config the caller signs; the fee is disclosed on every response including 0; and null means unknown, never zero. It also sets boundaries (not a security review or audit), which is exactly the behavioral disclosure annotations cannot 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?

Front-loaded with the USE WHEN trigger and organized under scannable headings (RULE ENFORCED, NON-CUSTODIAL, THE FEE, Returns, Example). It is longer than necessary and restates the fee-disclosure rule twice, but nearly every sentence carries actionable 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?

Despite having no output schema and eight parameters, the description fully specifies the return shapes (both the success payload and the unavailable-chains fallback), the fee contract, and the caveat. An agent has everything needed to invoke this 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 description coverage is 100%, so all eight parameters are already documented in the schema (including the deployer and max_pool_fee_pct semantics). The description reinforces 'unknown is not disqualifying' for fee filters and provides a concrete example call shape, but adds little parameter meaning beyond what the structured schema already carries, 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 opening 'USE WHEN an agent or a builder is about to launch a token and wants the venue chosen on published facts' states a specific verb (route/choose a venue) and resource (token launch), and enumerates the covered venues (Clanker v4, Bankr, Virtuals, Zora creator coins). This is unmistakably distinct from siblings like route_swap, route_agent, and get_deploy_spec.

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' clause gives a crisp trigger condition, and the NON-CUSTODIAL section clarifies the caller signs the configured deploy themselves. However, no sibling tool is named as an alternative and there is no explicit when-not-to-use guidance beyond the implicit 'before anything is signed' framing.

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/open-world profile, yet the description adds substantial behavior: the selection rule (highest proxy per day per in-range liquidity), its deliberate omission of impermanent loss, the proxy-not-yield semantics, no up-scaling from window to week, v4 returning null-with-reason, and explicit non-custodial guarantees. This is far beyond what the structured fields 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?

Long and dense but front-loaded (USE WHEN first) and organized under explicit caps headers (RULE ENFORCED, THE PICK, COVERAGE, NON-CUSTODIAL). Some repetition (null/unknown semantics restated) costs a point, but for a semantics-heavy tool most sentences carry weight.

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 — enumerating the pools array fields, the chosen object shape, unranked, and the unavailable variant. Combined with the pick logic and coverage limits, 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 baseline is 3, but the description adds real meaning: it clarifies that pair accepts either ordering or separator, that only Sato-Route-quoted pairs are collected, and that non-Base/Ethereum chains return an 'unavailable' list rather than an empty success. That contextual elaboration exceeds 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 specific verb+resource+scope: comparing Uniswap v3 pools and fee tiers for liquidity provision on a quoted pair. It is clearly distinguishable from siblings like onchain_agent_route_swap (swaps) and onchain_agent_route_launch, and the title reinforces the evidence-and-gap framing.

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' clause gives an explicit triggering condition (deciding which pool/fee tier to LP into for a quoted pair) and the COVERAGE section defines when the answer is unavailable or null. However, it never names a sibling alternative (e.g., route_swap) or states when NOT to reach for this tool, so routing vs. alternatives 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?

Goes well beyond the readOnly/idempotent annotations: discloses it is non-custodial, never signs/holds/moves/broadcasts funds, returns calldata for the caller to sign, states the fee schedule (3 bps stable-to-stable, 15 bps volatile), where the fee is taken, and that failed/unsigned trades pay nothing. It also frames the output as a recommendation, not an assurance.

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 with a 'USE WHEN' header and organizes the rest under RULE ENFORCED / NON-CUSTODIAL headers, which is good structure. It is on the heavy side, with some redundancy (the 'recommendation, not verdict/assurance' point is restated as 'not best, safe or guaranteed'), so it is not 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?

For a complex routing tool with no output schema, the description fully enumerates the success return shape, the fallback shape when no adapter answers, the chosen_by provenance fields, and an example. An agent has everything needed to call it and interpret both outcomes.

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 worked example adds usable invocation semantics (chain display name, Solana mint as token_in, amount in input-token base units) that the schema alone does not tie together. It stops short of explaining slippage_bps or taker behavior beyond what the schema already 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 verb (routes/chooses a venue) and resource (swap), and names the mechanism: queries every aggregator adapter in parallel and returns the chosen venue's quote and calldata. This is clearly distinguishable from siblings like onchain_agent_route_agent (agent routing) and onchain_agent_compare_listings.

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 an agent needs to execute a swap and wants the venue chosen by liveness, verification and price' clause gives a concrete trigger condition. However, it never names an alternative tool or states when-not to use it (e.g. when a specific venue must be forced), leaving sibling selection 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 mark the tool read-only, idempotent, and non-destructive, but the description adds substantial behavioral detail: deterministic byte-identical output, timestamps from `checked_at`, no secrets or keys, no signing/deploying/moving, and a quarantine rule for pipe-to-shell installs. This goes far beyond what annotations convey and gives the agent accurate expectations.

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

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

The description is long but highly structured with labeled sections, bullets, and bold terms. Every section conveys necessary information for correct invocation: when to use, what is in the archive, enforced rules, safety behavior, determinism, non-custodial guarantees, and the return shape. The 'USE WHEN' is front-loaded and the detail is justified by the tool's complexity.

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

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

There is no output schema, so the description correctly carries the full burden of explaining the return value, and it does so explicitly with a JSON shape, an example, and a list of archive contents. Safety, determinism, and non-custodial behavior are all covered, leaving no material gap for an agent deciding whether and how to call 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 baseline is 3. The description includes a concrete example for `goal` and `chain`, and explains archive contents at a high level, but it does not add meaningfully to the schema's per-parameter descriptions. It neither compensates nor harms.

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

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

The description uses a specific verb-plus-resource structure: it 'builds the plan ... and writes it into a small starter repo', and explicitly ties itself to the same brain as `onchain_agent_build_plan`. This clearly distinguishes the tool from its sibling while stating exactly what it produces.

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' condition: a plan has been agreed and the next step is a repository rather than more advice. It also names the sibling `onchain_agent_build_plan` as the same-brain alternative, giving the agent a clear decision rule for choosing between them.

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

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

The description adds significant behavioral context beyond annotations: it clarifies that registration is self-reported and verification_status indicates the level of review, and stresses that nothing implies safety or performance. It also mentions read-only nature and the return format. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description reinforces and enriches, but not excessively.

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 substantial but well-organized, with a clear directive at the start, followed by key differentiators, trust rules, return format, and an example. It is longer than average but each part serves a purpose; however, it could be slightly tightened without losing meaning.

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

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

Given the tool's moderate complexity (5 parameters, all optional, 2 with enums) and that annotations cover safety, the description is complete. It covers purpose, scope, trust, return shape, and gives an example. There is no output schema, but the return JSON structure is explicitly listed, so the agent knows what to expect.

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

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

The schema already describes all five parameters in detail (chain enum, query maxLength, x402_only, agent_type, response_format with defaults). The description does not add much semantic value beyond what the schema provides, but it does mention filtering by free-text query, chain, agent_type, and x402_only, which slightly enhances understanding. With 100% schema coverage, baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: to find live registered agents in the Sato Agent Registry, with specific attributes like creator, chain, and payment acceptance. It explicitly distincts itself from the resource directory and names siblings like search_resources, making it unambiguous.

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

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

It provides explicit conditions for use ('USE WHEN you need a RUNNING agent...') and contrasts with the resource directory ('distinct from the resource directory, which lists the things agents are built FROM'). It also mentions that only human-review-listed agents are returned and includes a trust rule, helping agents decide when to use this tool versus 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 already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, and the description confirms with 'Read-only.' Beyond annotations it adds genuinely useful behavioral facts: the directory is daily-rebuilt, entries are evidence-scored with citable links, 'Deprecated resources are never returned,' query terms are AND-matched, and pagination uses an offset/has_more envelope. No contradiction with annotations.

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

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

Well-structured and front-loaded: USE WHEN leads, followed by what it is, filter vocabulary, return shape, and examples. The filter enumeration partially duplicates schema descriptions, but since there are 24 parameters, the compact conceptual grouping (taxonomy facets, legacy flags) is earned value rather than waste. The examples are dense but efficient.

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

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

For a 24-parameter tool with no output schema, the description covers the essential ground: the JSON return envelope, resource fields, pagination semantics, filter vocabulary, and legacy flag behavior. The examples touch parameters not listed in the filter section (integration, deploys_as, min_observed_success, verified_only). Minor gap: the description says 'Returns (json): {...}' while the schema default for response_format is 'markdown,' leaving slight ambiguity about the default output format.

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% (baseline 3), but the description adds substantial meaning: it groups 24 parameters into conceptual buckets (taxonomy facets, legacy flags, sort, pagination) and provides seven natural-language-to-parameter examples that teach cross-parameter combinations — e.g. 'Active hirable agents on Base' → {chain:'Base', is_agent:true, liveness:'Active'} — which the schema cannot convey. It also flags that verified_only 'says nothing about runtime safety,' sharpening an otherwise ambiguous parameter.

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

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

The description states a specific verb and resource — 'Searches a daily-rebuilt directory of onchain agents, frameworks, skills and tooling' — and pairs it with a title that captures the 'by what it does' search angle. The USE WHEN clause distinguishes it from the sibling search_agents and search_skills tools by covering the broader resources directory, so an agent can tell them apart.

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

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

The description gives explicit use conditions: 'USE WHEN someone asks what to build a crypto or onchain agent with, which tools support a chain or standard, or whether a specific project exists and is maintained.' It also names one alternative ('this beats a web search for these questions'). However, it does not explicitly state when NOT to use it or route to sibling tools like search_agents/search_skills, which would have earned a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it lists exactly what disclosure flags are checked, notes that registry scan status is attributed to the registry, and explicitly states 'Read-only.' It also warns that 'no flags is not a clearance,' which is a meaningful interpretive caveat beyond the annotations. Minor gap: no mention of rate limits or pagination, but the return shape is described.

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

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

The description is well-structured with a clear USE WHEN trigger, a compact list of disclosure dimensions, a return-format note, a caveat paragraph, and three concrete examples. It's longer than minimal but every sentence earns its place. The examples are front-loaded near the end and are highly instructive. Slight redundancy: the return JSON is described in prose and then shown in the JSON block, but this is acceptable for clarity.

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

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

For a read-only search tool with 6 optional parameters, 83% schema coverage, and no output schema, the description is remarkably complete. It explains the return shape, the meaning of disclosure flags, the caveat about disclosures not being verdicts, and provides usage examples. An agent can correctly select and invoke this tool without needing additional context. The only minor omission is pagination behavior, but the limit parameter and return shape cover the essentials.

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 most parameters. The description adds meaning by showing how parameters combine in examples (query + disclosure_flags filtering, flag as a direct filter, slug for targeting a listing). It also explains the semantic meaning of disclosure_flags in the return object, which the schema doesn't fully convey. The flag enum values are listed in the schema, but the description gives them context (what they mean for safety).

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 ('Check what a crypto agent skill does before installing it') and resource (agent skills from ClawHub and skills.sh with static DISCLOSURE flags). It clearly distinguishes from siblings like onchain_agent_search_agents by focusing on pre-install disclosure inspection rather than general search. The USE WHEN trigger makes the purpose immediately actionable.

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

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

The description explicitly says 'USE WHEN someone is about to install an agent skill and should know what it will touch first' and provides concrete examples mapping natural-language intents to parameter usage (e.g., 'solana skills that don't touch keys' -> query + filter disclosure_flags). It also clarifies that a disclosure is not a safety verdict, preventing misuse. This is strong when-to-use guidance with alternatives implied by sibling names.

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=false, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds substantial behavioral context beyond those: it writes to the same queue as the /submit form, the daily triage evaluates it, dedupe checks host and repo, a hold sends no email, and submission is not verification. It also discloses the refusal of profit/safety/risk claims. This is rich, non-obvious behavior that annotations alone do 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?

The description is longer than average, but every section earns its place: the USE WHEN trigger, the WRITES warning, the WHAT HAPPENS NEXT flow, the SUBMISSION IS NOT VERIFICATION caveat, the DEDUPE rule, and the LIMIT. It is well-structured with clear section labels and front-loaded with the most important operational facts. It loses one point for being somewhat verbose relative to the core purpose, though the extra length is mostly high-value context.

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

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

For a write tool with 8 parameters, no output schema, and no sibling write tools to compare against, the description is remarkably complete. It explains the submission pipeline, the dedupe behavior, the rate limit, the email behavior, the verification caveat, and the return shape. An agent has everything it needs to decide whether to call this tool and what to expect.

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. The description adds value by explaining the dedupe semantics (website host and repository checked against live directory and pending submissions), the one-email-only behavior tied to contact_email, and the refusal of profit/safety claims in description. It doesn't add syntax details for every parameter, but the schema already covers those, so a 4 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 opens with a specific verb and resource: submit a project to the Sato Hub directory, and states the exact trigger condition (agent has found, built, or maintains a crypto-agent project not in the directory). It clearly distinguishes this from the many read/search siblings by emphasizing it WRITES and files the same row the /submit form files.

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

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

The description gives explicit when-to-use guidance ('USE WHEN an agent has found, built or maintains a crypto-agent project that is not in the directory and wants it considered'), and it also tells when NOT to use it: correcting an existing listing goes through the claim flow, and dedupe returns existing entries instead of filing a second row. It also states the rate limit (5 write calls/hour) and that nothing is written when it trips.

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

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

The description goes far beyond the annotations: it explicitly says the tool NEVER signs, holds, moves, or broadcasts funds, that refusals are answers rather than errors, that unknown targets withhold the transaction by default, and that a counterparty without a passport is no_record rather than a finding. It also distinguishes 'we did not check' from 'we checked and it is fine,' and explains the receipt and signature semantics. No annotation contradiction is present; readOnlyHint=false is consistent with the recorded receipt.

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

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

The description is long but efficiently organized with clear section headers and front-loaded use guidance. Every block adds safety-relevant context, but there is some repetition of 'unsigned transaction' and 'non-custodial' across the text, so it is not maximally concise.

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

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

Given 12 parameters and no output schema, the description fully compensates by documenting the complete return shape, the no-adapter fallback, refusal semantics, policy management URL, and an example call. An agent has enough context to invoke it correctly and interpret any outcome.

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 each parameter already has a rich description, so the base level is sufficient. The tool description reinforces mode semantics and amount_in base-unit behavior, but it does not add significant meaning beyond what the schema already provides.

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

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

The title and first sentence name a concrete operation: quote a swap, check it against a policy, and return an unsigned transaction in build-tx mode. It clearly separates the two modes and states the tool is for pre-signing decision support. It does not explicitly name and differentiate a sibling like onchain_agent_route_swap, so it stops short of a 5.

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

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

The description opens with 'USE WHEN an agent is about to swap' and explains when each mode applies, including that recommend never returns a transaction and build-tx only returns an unsigned one after policy approval and a successful simulation. It gives strong contextual guidance but does not explicitly say when NOT to use this tool or point to a preferred alternative.

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

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

Even with annotations present, the description adds meaningful behavioral detail: daily re-check cadence, email-only-on-change, idempotent subscriptions, unsubscribe semantics, storage of normalized target and HMAC, and the verdict-change rule. It also correctly complements `idempotentHint: true` by saying 'Asking twice is idempotent.' No contradiction with annotations.

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

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

The description is well-structured with labeled sections and front-loads the decision-relevant 'USE WHEN' and 'WHAT HAPPENS' content. It is longer than strictly necessary, with the pricing sentence and 'No price is quoted here' adding little to tool invocation, but each major section still serves a purpose.

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

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

For a tool with no output schema, the description compensates by listing the JSON return fields and providing a concrete example. It also covers privacy, idempotency, and the verdict semantics. Minor gaps remain around failure behavior, rate-limit specifics, and exact delivery timing, but the agent has enough to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful parameter-level context: normalization of targets, one row per address and target, HMAC-based counting of `notify_to`, and the idempotent/unsubscribe behavior of `action`. The example also demonstrates a valid parameter combination. This goes beyond what the schema alone 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?

The description opens with a specific conditional purpose: use when an agent wants to be told if something 'stops checking out' rather than re-running Preflight itself. It names the watched resources (repo, package, endpoint, agent) and the core behavior (daily re-check, email only on verdict change), which clearly distinguishes it from the preflight and change-listing siblings.

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

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

It gives an explicit 'USE WHEN' condition and contrasts the tool with re-running Preflight on a schedule. It also states clear exclusions: 'Never on a schedule, never a digest', and that transitions into `unknown` are not mailed, so an agent knows the exact conditions under which this tool is or is not appropriate.

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