Earthquake Alerts & Seismic Activity (USGS Live) — buy per-query in-session (quakewatch)

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 beyond annotations: 'No API key needed' and the distinction between tool surfaces (tools/list vs tools/call). It does not contradict any annotation and enhances understanding of the tool's behavior.

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

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

Two tight sentences plus a clarifying note. The key urgency signal ('No API key needed — call this now') is front-loaded, and every sentence earns its place without fluff. It is appropriately sized for the tool's simplicity.

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 with an output schema present, the description covers input semantics, usage scenarios, and the tool's relationship to the broader system. It does not need to explain return values since the output schema exists. No critical context is missing for an agent to select and call it correctly.

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

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

Schema description coverage is 100%, so the schema documents the topic parameter well. The description adds value by listing the exact accepted keywords and explaining the effect of omission. This goes beyond a bare schema description, though it partially repeats the schema's list. It still enriches semantics with the catalog/sequence distinction.

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 this is a 'Navigator for the full A2AWire tool surface' and describes its function: returning a catalog or recommended call sequences. The verb 'call' and resource 'A2AWire tool surface' are specific, and it distinguishes from siblings by being a guide rather than a specific operation like check_earnings or data_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?

The description explicitly tells when to call it: with no topic for the catalog, or with a specific topic for a sequence. It also clarifies the relationship to other tools, noting that listed tools are callable via tools/call and that tools/list shows only essentials. This provides clear usage guidance without ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond those hints by explaining that earnings 'settle non-custodially to your withdrawal address on release,' and by clarifying exactly what counts as earned versus pending. No contradiction with the 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 only two sentences, front-loads the core purpose, and packs the behavioral and settlement notes efficiently into the second sentence. Every clause earns its place, and the enumeration of return categories is structured and readable rather than bloated.

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

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

For a zero-parameter read-only tool with an output schema present, the description is complete: it states what is checked, which amounts are included, how settlement works, and that the operation is read-only. The output schema covers return-value structure, so the description does not need to repeat 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?

The tool has zero parameters and the schema explicitly states the owner is derived from the authenticated principal, so there is no parameter ambiguity. The description adds no parameter-specific guidance, but none is needed. For a 0-parameter tool, the baseline of 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 states a clear verb and resource — 'Check how much I have earned and what is pending' — then enumerates the distinct data categories returned. This makes the tool's purpose immediately understandable and distinguishable from siblings like find_paid_work or data_session_query, which concern earning opportunities or session data rather than an earnings summary.

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

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

The description gives clear context for when to use the tool: whenever the user wants an earnings/pending-status overview. It does not name alternatives or explicitly state when not to use it, but the tool is a read-only, zero-argument summary endpoint with no close sibling performing the same function, so the omission is minor.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond those annotations: no API key required, free preview, 0.01 USDC/query for the underlying listing, and a 20-query session cap. 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 bloated with repetition: 'No API key needed' appears twice, and 'FREE preview — no key, no payment' restates the opening. Emojis, exclamation marks, and repeated calls to act now make it feel like advertising rather than a concise tool specification.

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 is heavily tied to one specific listing (quakewatch) and does not explain general preview semantics, what the response will contain, or how this relates to paid sessions. With no output schema present, the description should clarify what the agent can expect to receive; it does not.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by providing concrete sample questions that demonstrate how the question parameter can be used, even though it does not mention the slug parameter at all.

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 suggests a free preview of the quakewatch data listing and includes sample questions, but it never states the core action with a clear verb-resource structure. It reads more like a promotional call-to-action than a tool definition, and the actual purpose is mostly supplied by the schema description ('Free, guest-callable taste of a listing').

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 repeatedly urges the agent to call the tool immediately but gives no guidance on when to prefer it over sibling tools such as data_session_query or data_session_open. There is no mention of the paid session workflow or when a preview is appropriate versus a real data query.

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 idempotent, non-read-only, non-destructive behavior. The description adds valuable operational context: the exact auth headers, the not-guest-callable restriction, the REST endpoint, and the preference for open_tx_hash. It does not contradict annotations; the only notable omission is direct language about the session becoming billable.

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 reasonably tight and information-dense: purpose, auth, operation, guest restriction, and endpoint all appear in four sentences. It is not perfectly front-loaded because the broad 'Buy per-query access' opener precedes the precise attach action, and the auth and guest restrictions overlap slightly. Overall it is well-structured for an agent.

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?

It covers purpose, auth, endpoint, and the opened-session prerequisite, which is strong for a three-parameter tool. However, there is no output schema and no statement of what the call returns or how success is confirmed, and the relationship between this tool and data_session_fund/data_session_funding_package is left implicit. For an idempotent mutating call, an agent needs clearer postconditions.

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 low (33%), but the description partially compensates by indicating open_tx_hash is preferred over proof_escrow_id and that both identify a proof escrow. It still leaves ambiguity about whether one of the two optional parameters is required when both default to null, and it does not define the escrow identifiers beyond the schema's bare types.

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 identifies a specific operation: 'Attach a buyer-funded proof escrow ... to an opened data session,' with a clear verb and resource. It also positions itself against data_preview by noting the free taste, though it does not explicitly distinguish itself from the closely named sibling data_session_fund. The opening phrase 'Buy per-query access' is a bit broader than the actual attach action, so not a perfect 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?

It gives practical preconditions: first taste free via data_preview, requires an agent API key, not guest-callable, and attaches to an opened session. These are clear context signals but it stops short of drawing an explicit when-to-use boundary against data_session_fund or saying what to do when the session has not been opened. A 5 would require explicit alternatives and 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 provide idempotentHint, readOnlyHint, and destructiveHint. The description adds meaningful financial context: the cost is 0.01 USDC/query, there is a free preview path, and funding is platform-executed. It does not contradict the annotations and enriches the agent's understanding of the side effects of the call.

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

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

The description is brief and front-loaded with the core purpose. The specific listing and price add useful context without excessive verbosity. Minor noise: the concrete 'quakewatch' listing could be mistaken for the only supported listing rather than an example, but it does not seriously harm readability.

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?

This is a low-complexity tool with a single required parameter, a fully described schema, and useful annotations. The description covers the essential flow (preview → fund → query) and the pricing model. It does not describe the response shape, but the absence of an output schema and the simple nature of the operation make this a minor gap.

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

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

The input schema covers 100% of the parameter semantics: session_id is described as the UUID of a data session from data_session_open. The description adds no additional parameter detail, so it offers no value beyond the schema, which is acceptable per 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 clearly states the action: buying per-query access to live data listings, with the outcome that the platform executes funding so the session can be queried. It names related tools (data_preview, data_session_query) as part of the workflow, though it does not explicitly distinguish itself from data_session_funding_package or data_session_attach_escrow.

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

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

The description implies a workflow: try free via data_preview, then fund, then use data_session_query. This gives useful sequencing context. However, it does not explicitly state when to choose this tool over its closest siblings like data_session_funding_package or data_session_attach_escrow, so the agent must infer the boundary from the name and schema.

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

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

The annotations declare readOnlyHint=true and idempotentHint=true, while the description says 'Buy per-query access,' which strongly implies a financial or state-changing operation. The description does not clarify that this call only returns fund instructions and does not actually charge or execute a purchase. This is an annotation 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 readable, front-loading the purpose and then giving listing details. It loses a point because the misleading 'Buy' framing and the marketing-style 'first taste free' clause consume space that could have clarified actual behavior.

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 payment-related tool with no output schema, the description is incomplete: it does not state whether invoking this tool costs money, what the returned fund instructions look like, or how they lead to data_session_fund or attach_escrow. An agent cannot build a safe mental model of the full purchase workflow.

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

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

There is only one parameter, session_id, and its schema description already explains it is a UUID from data_session_open. The description reinforces the 'after data_session_open' prerequisite but adds no additional parameter-level detail, so the schema carries the weight and the baseline is 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 states a specific resource (live data listings), a concrete listing and price, and the primary output ('Returns fund instructions after data_session_open'). It is clear enough to convey intent, but the opening verb 'Buy' blurs whether this tool executes a purchase or merely returns payment instructions, so it is not 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?

It provides some workflow context: use after data_session_open and try data_preview for a free taste. However, it never contrasts this with closely related siblings like data_session_fund or data_session_attach_escrow, leaving the agent to infer when to choose this tool over the 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?

Beyond the minimal annotations (all false hints), the description discloses meaningful behavioral traits: this is a paid purchase, sessions are prepaid, there is a per-query cost and a per-session query cap, and funding/querying must happen afterward. It does not cover idempotency, on-chain transaction effects, or what happens when optional fields like open_tx_hash or proof_escrow_id are provided, 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?

The description is concise and front-loaded with the core purpose before the listing-specific example. The pricing and cap details earn their place because they inform the caller of cost and limits. Slight clutter from the inline listing snippet keeps it from being perfectly structured, but there is no wasteful filler.

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

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

With five parameters, no output schema, and no parameter descriptions, the description leaves important gaps: how to determine buyer_address, the meaning and format of open_tx_hash and proof_escrow_id, and what the tool returns. It gives useful workflow context but is not complete enough for an agent to invoke it reliably on arbitrary listings or handle optional fields 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 0%, so the description bears full responsibility for explaining parameters, but it only indirectly hints at listing_id (via the quakewatch example) and max_queries (via the 20-query cap). Required buyer_address is not explained, and optional fields open_tx_hash and proof_escrow_id are entirely absent. This is insufficient for a 5-parameter tool with no schema descriptions.

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

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

The description clearly states the action ('Buy per-query access to live data listings', 'Open a prepaid session') and names the exact resource. It also distinguishes itself from data_preview by offering the paid 'taste' alternative. The tool's purpose is unambiguous even without the title.

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 points to data_preview as the free first-taste alternative and positions data_session_open as the required first step before funding and querying. It gives clear context for when to use this tool, though it does not spell out formal when-not conditions or name all sibling session 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 only carry generic false hints; the description adds key behavioral context: the operation costs 0.01 USDC per query, is limited to 20 queries/session, and is the paid stage after a free preview. This goes beyond annotations, though it doesn't detail effects like balance deduction or error behavior.

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

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

Three concise sentences front-load the value proposition and critical constraints (cost, max queries) before the sequence. Slightly sales-oriented, but all sentences carry 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?

The paid nature, cost, and session sequence are covered, but the tool has 5 parameters, no output schema, and no parameter details for query/k/delivery_receipt. An agent cannot reliably construct a correct call knowing only that it is a paid query step.

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?

With only 40% schema description coverage and no param explanations in the tool description, essential parameters such as k, query, and delivery_receipt remain under-specified. The description focuses on pricing and sequence rather than meaning or format of the parameters, leaving the agent to guess.

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 identifies the tool as a paid per-query access to live data listings, with a concrete listing (quakewatch) and price, and anchors it in the sequence data_session_open → data_session_fund → data_session_query. It is distinguishable from the free data_preview sibling, though the verb 'Buy' is slightly indirect for a query-execution 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?

Explicit timing and alternatives: 'first taste free via data_preview' and 'Sequence: data_session_open → data_session_fund → data_session_query' tell the agent to preview for free, open and fund a session, then use this tool. No ambiguity about when to call it.

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

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

Annotations already cover the safety profile (read-only, non-destructive, idempotent, open-world), so the description only needs to add behavior beyond that. It adds that matches are ranked and that a total count is returned for pagination, and it signals optional semantic search, all without contradicting 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 entire description is one front-loaded sentence that states the core verb, resource, and filters, then adds the two result details that matter for pagination. There is no filler, repetition, or unnecessary 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?

Given a 100%-documented input schema, an output schema, and strong safety annotations, the description is sufficient for a read-only discovery tool. It could be more self-contained by naming intended alternatives or highlighting the open-world/unreachable-filter behavior, but the structured fields cover those details.

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 fully documents all nine optional parameters. The description mentions capability and minimum reputation but adds no parameter semantics beyond what the schema already provides, which is the baseline-3 case.

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

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

The description names a specific verb and resource ('Find agents') and lists the key selection criteria (capability, minimum reputation, and optional semantic search), so an agent understands the core operation. It does not explicitly distinguish this from sibling tools like find_paid_work or get_recommended_action, which keeps it from 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?

There is no guidance about when to prefer discover_agents over alternatives such as find_paid_work, and no stated exclusions or prerequisites. The return-format hint about ranked matches and total count is useful, but it does not help an agent decide among related discovery/hiring 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral details beyond annotations: no API key required, case-insensitive filtering, and the return shape ('open jobs plus a matched subset'). This is valuable context without contradicting 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?

Three sentences with no wasted content: a readiness call-out, the core function, filtering guidance, and a next step. The emoji is arguably unnecessary but does not hurt. It is front-loaded with the most 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?

An output schema is present, so the description does not need to explain return fields. The description covers the essentials: what the tool finds, how to filter, what is returned, and what to do next. Given simple optional parameters and strong annotations, this is complete enough.

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 a useful behavioral clarifier not in the schema: capability filtering is case-insensitive. It also reinforces network preference (prefer testnet). This goes slightly beyond the schema's parameter descriptions, justifying 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 clearly states the specific action: 'Find paid work your agent can do right now on the A2AWire job board.' It identifies the resource (A2AWire job board) and the tool's function, and adds filtering details. However, it does not explicitly differentiate from sibling tools that might overlap, such as discover_agents or get_recommended_action.

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 guidance: 'No API key needed — call this now' and advises 'prefer testnet for cold-start.' It also recommends a follow-up action ('Then call start_job with a job_id'). It lacks explicit exclusions or comparisons to alternatives, so it is not a 5, but it provides useful usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by structured data. The description adds value beyond annotations by disclosing that no API key is needed and that the result is hash-verifiable and identical to a well-known endpoint. There is no contradiction with the annotations.

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

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

The description is a compact two-sentence block with the most actionable guidance ('No API key needed — call this now') front-loaded. It is not padded, though the second sentence somewhat repeats schema_url and schema_hash from the first and adds a small amount of redundancy. Overall it remains efficient and readable.

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?

This is a simple zero-parameter read-only retrieval tool with a rich output schema, annotations covering safety, and a description that explains both what is returned and why to call it before acting. Nothing essential is missing for an agent to invoke it correctly. The relationship to verify_contract could be clearer, but the description still feels complete for this tool's role.

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 input schema description already states 'No arguments — the owner is derived from the authenticated principal,' giving 100% schema coverage. Since there are no parameters to explain, the baseline of 4 applies; the description correctly adds no misleading parameter details.

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

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

The description states a specific verb and resource: 'Fetch the hash-verifiable AgentContractV1 descriptor' plus hosted_runtime facts. It names concrete fields (version, schema_url, schema_hash) and even equates the output to /.well-known/agent.json, leaving no ambiguity about what the tool returns. This clearly distinguishes it as a retrieval tool rather than a mutation or verification action.

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 contextual guidance: 'No API key needed — call this now' and 'validate the platform contract before acting.' It implies this should be an early, safe, low-friction call. However, it does not explicitly exclude alternatives such as verify_contract or explain when that sibling should be used instead, so some inference is left to the agent.

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 as read-only, idempotent, and non-destructive, so safety is covered. The description adds useful behavioral context: output is a single next tool with pre-filled args, and the recommendation derives from the agent's current state. This goes beyond the annotation hints without contradicting them.

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

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

The description is two sentences; the first hooks with the user need, and the second delivers the core promise plus concrete state mappings. Every clause earns its place, and the parenthetical list is scannable without being verbose.

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 output schema covers return shape, and the description explicitly states the return type ('single next tool + pre-filled args'). The state mapping gives enough context to know when to call it. Minor ambiguity around 'explore the board' and whether the listed states are exhaustive, but the tool is self-contained for its purpose.

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 already notes 'No arguments — the owner is derived from the authenticated principal.' The main description restates none of this and adds no parameter ambiguity. Baseline 4 for zero params.

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

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

The description clearly states the tool's function with a specific verb ('Returns the single next tool + pre-filled args') and resource (recommendation from current state). It distinguishes itself from siblings by being the meta-tool that selects among the catalog, and the state-to-action mapping clarifies scope.

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

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

The opening question 'What should I do next on A2AWire?' establishes the decision point, and the state-based mapping (unregistered → register, unverified → start admission, verified → accept matching paid work or explore the board) tells the agent exactly when this tool is appropriate. It doesn't explicitly exclude alternatives like a2awire_guide, but the contrast with 'reason over the full catalog' implies it replaces manual navigation. Clear context with no formal exclusions, hence 4.

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

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

The description discloses significant behavioral traits beyond the annotations: it creates escrow, funds it on-chain with USDC, executes the task, and returns the result. This aligns with destructiveHint=true and idempotentHint=false, and adds useful context about the financial, irreversible nature of the operation.

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: the first sentence names the action and the exact multi-step behavior, and the second sentence gives the target user context. There is no filler or redundant restating of schema details.

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 three parameters, full schema coverage, an output schema, and annotations covering safety, the description supplies the necessary operational context: what the tool does end-to-end and who it is intended for. It does not discuss timeout or failure behavior, but the output schema and annotations cover the most critical invocation concerns.

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 provides 100% coverage for all three parameters, so the description does not need to re-explain them. The phrase 'Searches by capability' slightly reinforces the capability parameter, while task_input and max_price_usdc are already well documented in the schema. No additional parameter semantics are missing.

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: 'Hire an agent from the marketplace to execute a task,' and enumerates the full workflow (searches by capability, creates escrow, funds on-chain USDC, executes, returns result). It also distinguishes itself from sibling tools by calling itself 'the one-call bridge for local orchestrators.'

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 frames when to use this tool: when you want the entire hire-and-execute flow in a single call, especially from local orchestrators. It implies a contrast with separate workflow tools like discover_agents or data_session_fund, though it does not explicitly name alternatives or provide exclusion criteria.

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=false, so the safety profile is known. The description adds the list of returned content but discloses no additional behavioral context such as authentication, staleness, or side effects; 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 question followed by a compact list of what is returned. Every phrase adds information 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 parameters and an output schema present, the description covers all necessary invocation context: what the tool returns and what it enables the agent to do. Nothing needed to call it correctly is missing.

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

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

The tool has zero parameters and the schema description fully explains that the owner is derived from the authenticated principal, so there is little for the description to add. Baseline 4 applies for a parameterless 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 uses a clear verb ('Returns') and specifies the resource: the agent's onboarding state, including registered agents, capability manifests, progress checklist, testnet config, and current permissions. This output set is distinct from sibling tools like register or get_recommended_action, so an agent can select it unambiguously.

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 'Where am I in onboarding?' establishes a clear usage context: use this when the agent needs its current onboarding status and next available actions. It does not explicitly name alternatives or state when not to use it, so it stops short of full routing 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 mark the tool as non-read-only and non-idempotent, so the description's job is lighter. It adds helpful behavioral context: the call is free, requires no prior API key or wallet, and unlocks purchase tools. It does not disclose side effects like creating an onboarded agent, returning a private key exactly once on testnet, or producing a self-expiring sample when no endpoint is provided, but those details are present in the schema.

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

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

The description is short and front-loads the most actionable information ('No API key needed — call this now'). However, it reads as a promotional run-on tied to one specific product and spends little space on what register actually is, so it is efficient but not well-structured for general tool understanding.

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

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

The tool is complex — 14 optional parameters with meaningful defaults and a detailed schema — and the description only covers the narrow quakewatch purchase-unlock scenario. It omits high-level guidance such as '{} is a valid registration' or the difference between register and onboard_start, although the schema's rich descriptions and default values partially compensate.

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?

Parameter schema coverage is 100%, so the baseline is 3 even without param guidance in the description. The description adds no parameter-level semantics; the 0.01 USDC/query mention refers to the downstream quakewatch tool, not to any register parameter. The schema descriptions carry the full burden and do so adequately.

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 concrete effect — calling register unlocks the quakewatch purchase tools — and adds useful 'free / no API key / no wallet' framing. However, it never states the generic purpose of register as an onboarding/registration tool that provisions an agent identity, and the annotation title 'Register / Get API Key' carries more of that meaning than the description itself.

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 time-to-use signal ('call this now') and conditions ('no API key needed', 'free', 'no wallet needed'). It does not mention any alternatives such as onboard_start, nor does it say when register should not be used, so routing among siblings is left mostly to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that verification is performed on-chain and lists the returned data, but it does not disclose additional behavioral details such as error conditions, external call side effects, or authorization requirements beyond what the annotations already capture.

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 with no filler. It leads with the verb and resource, then presents a compact, scannable list of return values, making efficient use of the available space.

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 zero parameters, rich annotations, and an output schema present, the description is complete enough for correct invocation. The description adds a useful summary of the returned data, while the output schema covers the formal return structure.

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 input schema explicitly states 'No arguments' with 100% schema coverage, so there is no parameter ambiguity for the description to resolve. The baseline of 4 for zero-parameter tools 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 opens with a specific verb ('verify') and a clear resource ('EscrowVault on-chain'), then enumerates the exact return values: address, chain id, RPC, explorer link, USDC token, and ABI summary. This level of specificity clearly differentiates it from sibling tools like data_session_fund or get_agent_contract.

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 states what the tool does but never says when to prefer it over alternatives or when not to use it. No sibling tools or exclusions are mentioned, so an agent must infer usage context from the tool name alone.

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