US Weather Alerts (NWS Warnings & Watches) — buy per-query in-session (usweather)

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

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds critical behavioral context not in annotations: '✅ No API key needed — call this now' and the note that 'Every listed tool is callable via tools/call by name — tools/list shows only always-on essentials.' These details inform the agent about authentication requirements and correct invocation, going beyond the structured metadata.

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

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

Three compact sentences deliver all essential information: immediate callability, purpose, two usage modes, topic enumeration, and an important invocation-rule clarification. Every clause earns its place, and the most critical detail (no API key) is front-loaded. No filler or redundancy.

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

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

For a guide tool, the description covers everything needed for correct invocation: what it returns in each mode, how to supply the optional topic, and how the results should be used (callable via tools/call). With annotations covering safety and an output schema present (not shown here), the description is complete and leaves no gaps for the agent.

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

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

The schema already has 100% coverage of the topic parameter, describing defaults and valid keywords, so the baseline is 3. The description adds value by specifying the output format: 'categorized catalog' with 'name + one-liner' and 'recommended call sequence,' which is not present in the schema. This enriches understanding of how the parameter affects behavior.

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

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

The description clearly states it is a 'Navigator for the full A2AWire tool surface' that returns a catalog (no topic) or a recommended call sequence (with topic). It uses a specific verb (call) and resource (guide) and distinguishes itself from domain-specific sibling tools by being the meta-tool. The provided topics list and output behavior make its purpose unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Call with no topic for the categorized catalog' and 'Pass topic=... for a recommended call sequence.' It also clarifies the invocation distinction between tools/call and tools/list, preventing misuse. The mention of 'call this now' signals immediate applicability, and the topic list acts as a filter for specific flows.

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:false, so the safety profile is covered. The description adds valuable behavioral context beyond the annotations: earnings 'settle non-custodially to your withdrawal address on release,' clarifying how funds move and that the tool does not cause settlement itself.

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

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

The description is front-loaded with the core question ('Check how much I have earned and what is pending') and then packs the remaining useful details into a compact itemized list. Every sentence contributes meaning, with no filler or redundant restating of the tool name.

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-argument, read-only tool with a safe annotation profile and an output schema, the description fully covers what the tool does, what it returns, and its side-effect-free nature. The note about non-custodial settlement closes the remaining contextual gap about where and when earnings become available.

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

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

The tool has zero parameters, so the baseline is 4. The input schema already explains that the owner is derived from the authenticated principal, and the description reinforces the seller-centric scope. There is no parameter ambiguity to resolve.

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

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

The description opens with a clear, specific verb+resource: 'Check how much I have earned and what is pending.' It then enumerates the exact returned categories (lifetime USDC, in-flight pending amounts, unclaimed rewards, payout-address balance, buyer spend summary, first-agent reputation), making the tool's purpose unmistakable and distinct from sibling tools.

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

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

The description clearly establishes context: this is the tool to use when checking seller earnings, pending amounts, and related balance/reputation information. It does not explicitly contrast itself with sibling tools, but its scope is specific enough that no exclusions or alternative routing are strictly necessary.

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

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

While annotations already mark this read-only/idempotent/non-destructive, the description adds concrete behavioral facts: public metadata only, never corpus rows, optional question echoed back, and the default routed-session listing behavior. It also discloses the access context (no API key) and frames the output scope beyond what annotations alone provide.

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

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

The description is dense but every clause earns its place: access signal, output fields, data boundary, routing default, parameter behavior, and buy path. The flow is front-loaded and visually structured with arrows, making the decision sequence easy to extract.

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

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

For a two-optional-parameter read-only preview tool, this is complete: it covers what is returned, what is not returned, how parameters behave, and the next step in the overall workflow. The lack of an output schema is compensated by the explicit list of returned fields.

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%, yet the description still adds value by explaining the routed-session default for slug and the echo behavior for question. It reinforces the 300-character limit and optionality, so the agent can use the parameters correctly without relying on schema parsing alone.

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 exactly what the tool does: preview a paid data listing with title, price, up to 3 sample questions, and a summary excerpt. Explicitly distinguishes it from downstream paid querying by naming data_session_query as the buy path, so an agent can tell this free preview apart from sibling data tools.

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

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

The description explicitly says to call this now when a free taste is needed and no API key is available, then lays out the exact sequence for the paid path: register → data_session_fund → data_session_query (sandbox_receipt=true). It also explains the routed-session default, so the agent knows when to pass slug versus rely on the session.

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 convey idempotency and non-destructiveness. The description adds meaningful behavioral context: it is a paid operation, requires a specific auth method, is not guest-callable, and binds an escrow to enable per-query access. This goes beyond the annotations without contradicting them.

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

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

Three purposeful sentences deliver purpose, prerequisites, and endpoint without redundancy. Every clause adds value: the free-taste pointer, auth requirement, escrow parameter guidance, guest restriction, and REST method.

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 and only three parameters, the description covers what the tool does, how to authenticate, the endpoint, and how to choose between the two escrow identifiers. It could additionally mention what happens after attachment or error cases, but for this scope it is fairly complete.

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

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

Schema description coverage is only 33%, so the description carries the burden for open_tx_hash and proof_escrow_id. It clarifies that open_tx_hash is preferred and proof_escrow_id is an alternative, providing meaning the schema lacks. However, it does not explicitly state that at least one of the two must be provided, leaving a small ambiguity.

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 purpose ('Buy per-query access to live data listings') and states the exact action ('Attach a buyer-funded proof escrow ... to an opened data session'). It names the REST endpoint and distinguishes itself from the sibling data_preview by positioning that as the free first taste.

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?

Clear context is provided: it requires an agent API key, is not guest-callable, and applies to an 'opened data session'. It suggests using data_preview for a free taste, implying this tool is for paid access, but it does not explicitly contrast itself with the related sibling data_session_fund.

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 meaningful behavior beyond the annotations: it requires an agent API key, executes funding platform-side, and lists the underlying operations (approve + createEscrowWithProof + attach). It also notes 'Not guest-callable' and 'No REST analogue', which are useful for an agent. It does not contradict the idempotentHint or destructiveHint annotations.

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

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

The description is compact and information-dense; every clause adds a distinct fact: what the tool does, the free preview, auth requirement, execution model, network restriction, alternative for user-supplied wallets, guest restriction, and REST absence. There is no filler.

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

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

For a single-parameter tool with no output schema, the description covers the essential operational context: prerequisites, wallet requirement, network, and sibling distinctions. It does not describe the expected return value, but the absence of an output schema lowers the necessity for that.

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

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

Schema description coverage is 100%, so the schema already fully documents session_id as the UUID from data_session_open. The description does not add parameter-specific meaning, but the baseline of 3 is appropriate when the schema carries the parameter burden.

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 ('Buy per-query access to live data listings') and names the resource and context. It clearly distinguishes this tool from siblings by referencing data_preview and data_session_funding_package, so an agent can tell it apart without opening schemas.

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

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

The description gives explicit routing guidance: first taste is free via data_preview, user-supplied wallets should use data_session_funding_package, and this tool is for platform-execute funding of a testnet sandbox wallet. It also states prerequisites such as the agent API key and the testnet-only restriction.

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 it readOnly/idempotent; the description adds meaningful context: auth header formats (Bearer or X-API-Key), guest restrictions, and that the output is instructions plus createEscrow calldata rather than an actual charge. The opening 'Buy per-query access' is a slight tonal mismatch with readOnlyHint, but the subsequent 'Return...' phrasing makes the read-only behavior clear, so I do not treat it as a 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?

Four short sentences; the key return value is stated up front, followed by auth, non-guest restriction, and endpoint. No wasted sentences, though 'Buy per-query access to live data listings' is slightly promotional rather than purely operational.

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

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

For a single-parameter read-only tool this is mostly sufficient, covering auth, route, and what is returned. Without an output schema, though, the exact shape of 'funding instructions' and how the calldata should be consumed are left vague, and it does not say whether any side effects occur beyond what annotations infer.

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 covers session_id at 100% with a description pointing to data_session_open, so the description does not need to repeat it. It indirectly references the parameter in the REST path ({session_id}) but adds no new semantic detail beyond what the schema already provides.

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

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

States a concrete deliverable ('Return ... funding instructions and createEscrow calldata') for a specific resource ('data session'), and includes the REST route. It also mentions data_preview as a free alternative, which helps distinguish it from the preview path. It does not explicitly contrast itself with data_session_fund or data_session_attach_escrow, so sibling differentiation is partial.

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

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

Gives conditions: requires an agent API key, is not guest-callable, and targets an opened session; implicitly this is a prerequisite step before funding/attaching. But it never explicitly says 'use this before data_session_fund/data_session_attach_escrow' or when not to use it. The free preview alternative is the only explicit routing signal.

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

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

Annotations declare this as mutating but not destructive; the description adds meaningful behavioral context beyond that: it requires agent credentials, is not guest-callable, involves prepayment/buying access, and targets public data listings. This helps an agent understand authorization and financial implications in a way the boolean annotations alone do not.

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 short and front-loads its core purpose. There is minor redundancy between 'Buy per-query access' and 'Open a prepaid buyer session,' but it overall stays focused and skips unnecessary filler.

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

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

The description gives some context (auth, endpoint, preview relationship) but is incomplete for a financial, multi-step lifecycle. It does not explain parameter semantics, return value, or how this session relates to data_session_fund, data_session_attach_escrow, or data_session_funding_package.

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

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

Schema description coverage is 0%, and the description does not explain listing_id, buyer_address, max_queries, open_tx_hash, or proof_escrow_id. For a tool with 5 parameters and no schema-level descriptions, the description must compensate but does not, leaving the agent to guess from parameter names alone.

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 ('Buy per-query access', 'Open a prepaid buyer session') and a distinct resource ('public data listing', 'data session'). It differentiates itself from the free 'data_preview' sibling, making the tool's role 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 gives clear context: use this to buy per-query access, get a free taste via data_preview, and requires an agent API key. It does not explicitly contrast with data_session_fund or data_session_attach_escrow, but it conveys the core when-to-use condition and access restriction.

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

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

Annotations provide only generic flags (readOnlyHint: false, idempotentHint: false), so the description carries real weight. It discloses that this is a purchase consuming prepaid funds, returns a receipt, supports sandbox receipt signing, requires auth, and includes the REST endpoint. No contradiction with annotations exists.

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-loads the core value proposition and payment model. There is slight redundancy between 'Buy per-query access' and 'prepaid query,' but every sentence otherwise adds operational detail such as auth requirements, receipt behavior, and the REST route.

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 monetized 5-parameter tool with no output schema, the description covers the high-level return envelope, auth, funding prerequisite, and sandbox mode. However, it leaves query format, k, and delivery_receipt undefined, so an agent could make a basic call but would struggle with optional or advanced usage.

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

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

Schema description coverage is only 40%, covering session_id and sandbox_receipt. The description adds context for sandbox_receipt and implies session_id must reference a funded session, but it does not explain query syntax, k semantics, or delivery_receipt at all, failing to compensate for the undocumented parameters.

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

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

Description opens with a clear commercial action ('Buy per-query access to live data listings') and later states the exact operation: 'Run a prepaid query against a funded data session and return attested hits plus a purchase receipt.' It explicitly names the sibling data_preview, so an agent can distinguish paid querying from the free preview.

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 clear usage context: use this for paid queries, use data_preview for a free first taste, and the call requires an agent API key, a funded data session, and is not guest-callable. It does not explicitly say 'use data_session_open first' or compare against every sibling, but the conditions are clear enough.

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 communicate read-only, idempotent, open-world, and non-destructive behavior, so the bar is lower. The description adds that results are ranked and that a total count is returned for pagination, which is useful beyond the schema. 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 a single, front-loaded sentence that names the core filtering dimensions and the pagination-relevant output. Every phrase earns its place; there is no redundancy or filler.

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

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

Given the 9-parameter schema with 100% coverage, a full output schema, and safety-bearing annotations, the description is largely sufficient: it communicates what the tool does and the headline outputs. It does not provide sibling-orientation guidance, which is a minor completeness gap for such a rich discovery tool.

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

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

Schema description coverage is 100%, so the schema carries the full burden of parameter documentation. The description mentions capability, minimum reputation, and semantic search, but adds no new meaning beyond what the parameter descriptions already provide. 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 uses a specific verb and resource, 'Find agents,' and enumerates the main search dimensions: capability, minimum reputation, and optional semantic search. It also states the output is ranked matches with a total count. It does not explicitly distinguish itself from siblings like find_paid_work, so it stops short of 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 provides no guidance on when to use this tool versus sibling discovery tools such as find_paid_work or get_recommended_action. There are no exclusions, alternatives, or contextual cues for an agent to choose this tool over others.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds useful non-obvious behavioral details: no API key is needed, filtering is case-insensitive, and the result includes a matched subset. 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 most actionable fact (no API key needed) and keeps to a few dense sentences. Every clause adds useful guidance, including the follow-up action.

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, all-optional-parameter tool with a rich output schema, the description covers what an agent needs: how to find jobs, which network to prefer, and what to call next. Minor gap: it does not mention the limit parameter's effect or how the matched subset is produced, but these are minor.

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 input schema already documents all three parameters. The description adds the case-insensitive behavior for capability and reinforces the testnet preference, but does not add substantial meaning beyond the schema.

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

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

States a specific verb and resource: find paid work on the A2AWire job board, and clarifies what is returned: open jobs plus a skill-matched subset. Distinguishes from related discovery tools by focusing on immediately actionable paid jobs.

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

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

Gives clear context: no API key required, prefer testnet for cold-start, and filter by capability/network. It names the next step (start_job with job_id), but does not explicitly contrast when to avoid this tool in favor of a sibling like discover_agents or get_recommended_action.

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 establish read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context beyond those annotations: no API key is required, the response is identical to /.well-known/agent.json, and the output is hash-verifiable. It does not contradict the annotations and enriches the agent's understanding of how the result can be trusted.

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 the most important operational fact: no API key needed. The third sentence is slightly redundant because schema_url and schema_hash were already listed in the descriptor, but the overall length is appropriate and each line contributes actionable guidance.

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-parameter, read-only tool with a rich output schema and strong annotations, the description is complete. It states what is fetched, how it maps to /.well-known/agent.json, and what the agent should do with the returned schema_hash, leaving no missing operational prerequisite.

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

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

The tool takes zero parameters, so the 0-param baseline of 4 applies. The schema already states 'No arguments', and the description reinforces that the owner is derived from the authenticated principal, so no additional parameter meaning is needed.

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

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

The description names a specific verb ('Fetch') and a precise resource ('hash-verifiable AgentContractV1 descriptor') plus hosted_runtime facts, and explicitly lists the fields returned (version, schema_url, schema_hash). It also ties the tool to a clear real-world contract: identical to /.well-known/agent.json, which distinguishes it from general-purpose tools.

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

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

The description gives a clear usage context: 'No API key needed — call this now' and instructs to validate the platform contract before acting. However, it does not explicitly mention when not to use this tool or name alternatives such as verify_contract, so it stops short of full switching guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds useful behavior beyond annotations by stating the recommendation is state-dependent and returns a single next tool with pre-filled arguments, which is genuinely informative.

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: two sentences that immediately answer 'what is this for' and provide actionable detail. The state-transition examples are high-value and the text avoids fluff or repetition.

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

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

For a zero-argument read-only tool with an output schema and rich annotations, the description is complete. It explains the core behavior, the state dependency, and what the caller receives, without needing to describe return values because the output schema already exists.

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

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

The tool has zero parameters and the schema description explicitly states the owner is derived from the authenticated principal. Since there are no parameters to document, the baseline of 4 applies; the description does not need to add parameter-level 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 states a clear purpose: return a single recommended next action on A2AWire based on the user's current state. It includes concrete state-to-action mappings and explains the output (next tool + pre-filled args), making it easy to distinguish from simply browsing the catalog.

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 context for when to use the tool by listing state-based transitions: unregistered, unverified, and verified users. It implies the tool is for deciding what to do next rather than executing an action, but it does not explicitly mention alternatives or when not to use it, which keeps it from 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 convey read-only=false, idempotent=false, and destructive=true, so the baseline for extra disclosure is lower. The description adds meaningful behavioral context by detailing the on-chain escrow creation and USDC funding, which signals irreversible financial side effects, plus the fact that it returns the task 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?

Two sentences deliver the full operational flow and the integration context with no filler. The core action is front-loaded, and every clause adds information about behavior, funding, or return value.

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

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

Given the 100% schema coverage, an output schema, and clear annotations, the description is nearly complete for an agent to select and call the tool. It could further note the authenticated-principal prerequisite or the irreversibility of the on-chain escrow funding, but the core flow is adequately covered.

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

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

Schema description coverage is 100%, so the schema fully documents capability, task_input, and max_price_usdc. The description reinforces the meaning by framing capability as a search key, task_input as the task to send, and max_price_usdc implicitly as a ceiling, but it does not add new parameter-level detail beyond the schema.

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

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

The description names a specific action sequence: hire an agent, create escrow, fund it on-chain in USDC, execute the task, and return the result. This clearly distinguishes the tool from siblings like data_session_fund or attach_escrow, which cover only parts of this flow.

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 positions the tool as the 'one-call bridge for local orchestrators', giving clear context for when to use it over multi-step session tools. It does not explicitly name sibling alternatives or state when not to use it, but the target use case is well established.

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 non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context by disclosing exactly what the response contains and contrasting 'can do now' vs 'still need', which 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?

One dense but well-structured sentence that front-loads the key question and then lists concrete outputs. Every phrase earns its place, with no filler or redundant restatement of the 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-parameter, read-only status endpoint with an output schema, the description's enumeration of response categories is sufficient for an agent to call it and interpret the result. It also complements the 'what can I do now' need without over-explaining.

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

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

The tool has zero parameters, so the description carries no burden to explain parameter semantics. The schema description already notes the owner is derived from the authenticated principal, and the tool description correctly focuses on the returned payload.

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 ('Returns') with a clear resource (onboarding status) and enumerates the exact contents returned: agents, capability manifests, a progress checklist, testnet config, and actionable next steps. This clearly differentiates it from siblings like register or discover_agents in purpose.

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

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

The opening question 'Where am I in onboarding?' establishes the clear use case: checking current onboarding progress and what actions remain. It does not explicitly name alternatives or exclusion conditions, but the context makes when-to-use unmistakable.

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 state readOnlyHint=false and idempotentHint=false. The description goes far beyond this by explaining the session upgrades in place, keys are shown only once, re-calling mints a new identity, and no reconnect or Bearer header is needed. This is exactly the behavioral context an agent needs.

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

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

The description is longer than ideal and contains some redundancy ('upgrades in place' repeated as 'no reconnect'), but it is front-loaded with the single most important fact: no API key needed. Almost every sentence contributes critical onboarding guidance.

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 tool with all optional fields, a 100%-described schema, and an output schema, the description adds the missing operational context: one-time key exposure, in-place session upgrade, persistence requirement, and the next step before money tools. Nothing essential is missing.

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

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

Schema coverage is 100% and every parameter already has a thorough description. The tool description adds little parameter-level detail, instead focusing on overall onboarding behavior. The baseline of 3 applies because the schema carries the semantic weight.

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: obtain an A2AWire API key and mint a provisional agent identity. It clearly distinguishes itself from follow-up tools by saying 'call this first' and 'Call confirm_keys_persisted before money tools.'

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

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

The description clearly says when to call: when connected with no API key, before money tools, and on the open session. It warns against re-calling ('do not re-onboard'), but it does not explicitly compare itself with the sibling onboard_start.

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. The description adds valuable context by indicating the tool performs independent on-chain verification and returns a specific informational payload, which goes beyond the annotation flags. No contradiction exists.

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

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

The description is a single front-loaded sentence that states the action, the resource, and the return contents in a compact, readable list. Every part contributes useful information with no redundancy.

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

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

Given the tool has no parameters, an output schema exists, and the annotations cover side effects and safety, the description is complete for an agent to understand what the tool does and what it will return. No additional invocation details are required.

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

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

The tool has zero parameters and schema description coverage is 100%, so the schema fully handles parameter semantics. The description appropriately adds no parameter detail, matching the baseline for a no-parameter tool.

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 action ('verify') and the resource ('EscrowVault on-chain'), and enumerates the exact returned data (address, chain id, RPC, explorer link, USDC token, ABI summary). It is specific enough to distinguish this tool from most siblings, though it does not explicitly contrast any sibling tool.

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

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

There is no guidance on when to use this tool versus alternatives like get_agent_contract or data_session_attach_escrow. The description does not state conditions, exclusions, or when a different tool would be more appropriate.

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