Show HN Launches — buy per-query in-session (showhnwatch)

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds the note 'No API key needed', which is context about authentication requirements. It does not contradict the annotations and provides additional useful behavioral clues.

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 relatively concise but includes some promotional language ('call this now') and a redundant mention of the catalog behavior. However, it is structured well, front-loading key information and keeping each sentence purposeful.

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 is complete. It states what the tool returns, when to use it, and even mentions related capabilities (tools/call vs tools/list). No critical context is missing for an agent to decide to invoke 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 schema description covers the parameter fully, listing valid keywords and the default behavior. The tool description adds context about the recommended call sequences, slightly enhancing the semantic meaning beyond the raw 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 clearly states the tool's purpose as a navigator for the full A2AWire tool surface, returning a catalog or recommended call sequence. It distinguishes itself from sibling tools by being a meta-guide rather than a specific 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?

It explicitly explains when to call with no topic (for catalog) and when to pass a topic (for a recommended sequence). This gives clear usage guidance and implicitly suggests that for specific actions, one would use the relevant tool directly.

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?

Explicitly says read-only and non-custodial, and clarifies that earnings settle to the withdrawal address on release. This goes beyond the readOnlyHint annotation by explaining the funds-flow 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?

The description is reasonably compact, although the opening sentence and the detailed list overlap slightly. Overall it's focused and not padded.

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

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

The description lists all major return categories and mentions read-only behavior. Since output schema exists, it doesn't need to reproduce exact return types, but it gives enough context for an agent to know what it will get.

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?

No parameters are defined, and the schema description explains the owner is derived from the authenticated principal. There is nothing ambiguous for an agent to fill in.

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 action (check) and resource (earnings), and enumerates what's included. It also distinguishes from sibling tools by focusing on read-only earnings status rather than funding, hiring, or contract actions.

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

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

The description makes clear this is for checking earnings and pending amounts, which implies when to use it. It doesn't explicitly contrast with sibling tools, but the purpose is unambiguous enough for selection.

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, so the safety profile is covered. The description adds useful behavioral context: no API key required, free preview, a per-query price for the underlying listing, and a query-per-session limit. It does not contradict the annotations, though the mention of 'Price 0.01 USDC/query' could briefly confuse an agent into thinking this tool itself is paid.

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 urgent call to action ('No API key needed — call this now') and includes valuable sample questions. However, it repeats the free/no-key/no-payment message multiple times, and the promotional emoji-laden tone adds noise without adding informational 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?

For a simple tool with only two optional parameters, the description covers key operational facts like pricing, session limits, and example questions. It does not explain what the tool returns, and with no output schema the agent is left to infer the response shape; the schema's note that the question is 'echoed back' is also not surfaced in the description.

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

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

Schema description coverage is 100%, so the schema already documents both slug and question well. The description adds concrete sample questions that map directly to the question parameter, and it names the current listing slug (showhnwatch), giving practical examples an agent can use immediately.

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 free preview for the showhnwatch listing and includes sample questions, making the core purpose clear. However, it never explicitly states 'preview this data listing' in plain terms, relying on the phrase 'FREE preview' and the annotation title. It does not differentiate itself from siblings like data_session_query beyond implying free access.

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 strongly implies the tool is for trying a listing without an API key or payment, saying 'No API key needed — call this now' and 'FREE preview — no key, no payment.' It does not explicitly say when not to use it or mention alternatives such as data_session_query or data_session_open, leaving the routing decision mostly implicit.

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

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

Beyond the readOnlyHint=false annotation, the description discloses authentication requirements, the guest-call restriction, the REST endpoint, and the preference for open_tx_hash over proof_escrow_id. This adds meaningful behavioral context without contradicting 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 three sentences, front-loaded with the core purpose, followed by auth requirements, prerequisites, and the endpoint. Every sentence contributes practical information with 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 tool with no output schema and modest complexity, the description covers purpose, prerequisite session, auth, guest restriction, REST endpoint, and the two escrow identifier options. The main gap is that it does not explicitly state that at least one of open_tx_hash or proof_escrow_id must be supplied, despite the schema listing only session_id as 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?

Schema description coverage is only 33%, so the description must add meaning. It does by explaining that open_tx_hash and proof_escrow_id refer to the buyer-funded proof escrow and by indicating that open_tx_hash is preferred. It could clarify format and whether one is strictly required, but it adds value beyond the schema.

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

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

The description states a specific verb and resource: attach a buyer-funded proof escrow to an opened data session. It also explains the broader purpose (buy per-query access to live data listings) and distinguishes itself from the free data_preview path, making the tool's role clear even among siblings.

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

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

It provides clear usage context: use this after opening a data session, requires an agent API key, and is not guest-callable. It also mentions data_preview as the free first taste, giving an alternative. It does not explicitly enumerate when not to use related funding tools, but the guidance is sufficient for basic routing.

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

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

Annotations already cover readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds that funding is 'platform-executed' and that access is per-query, which is useful, but it does not disclose side effects such as balance deduction or session state changes beyond what annotations imply.

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 core purpose. The specific listing and price add context but are somewhat tangential to the tool's general behavior; still, there is no wasted wording.

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 one-parameter tool with a fully documented schema and safety annotations, the description covers the main workflow: preview, fund, query. It does not explain return values or how this relates to data_session_funding_package, but those are not essential for a correct call.

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

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

Schema coverage is 100%, and the single session_id parameter is already documented as a UUID from data_session_open. The description adds no parameter-specific meaning, so the baseline of 3 applies.

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

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

The description states a clear action ('Buy per-query access') and a specific resource ('live data listings'), and names a concrete listing. It distinguishes itself from data_preview by noting the free first taste, but does not explicitly differentiate 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 provides clear usage context: preview first via data_preview, then fund, then query via data_session_query. It implies the ordering but does not explicitly state when not to use this tool or name alternative funding-related siblings.

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

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

The description says 'Returns fund instructions' which aligns with the readOnlyHint=true annotation (no actual transaction is performed). It does not contradict the annotations, nor does it add significant detail beyond what the annotations already imply about side effects.

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 well-structured, using two sentences to convey the purpose, the specific listing, the price, and the relation to other tools. No superfluous words or redundant 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?

Given the tool's simplicity (one parameter, no output schema), the description covers the core functionality and timing. However, it fails to distinguish itself from the sibling data_session_fund, creating potential ambiguity about the exact role this tool plays in the funding 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?

The schema description covers 100% of the parameter (session_id) and clearly states it is a UUID from data_session_open. The description does not add any additional semantic information about the parameter beyond what is already in the schema, so the baseline score of 3 applies.

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

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

The description clearly states the tool's function: buying per-query access to live data listings, with a specific example (showhnwatch) and price. It also mentions the relationship to data_preview and data_session_open, making the purpose unambiguous.

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

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

The description mentions using data_preview for a free taste and that it returns fund instructions after data_session_open, but it does not differentiate this tool from the sibling data_session_fund, which likely has a similar or overlapping purpose. An agent could be confused about which tool to use for funding a 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?

It discloses the per-query cost and max session queries, which provides some financial transparency. However, it doesn't mention side effects like creating a blockchain transaction, that the operation is non-idempotent, or that the session requires funding before querying—critical details for a tool that is not read-only.

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

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

The description is brief and front-loaded with the main purpose, and it avoids excessive detail. The phrasing is somewhat choppy and includes a specific listing name and price, which are arguably extraneous, but overall it is concise and scannable.

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 provides a high-level workflow (open, fund, query) and pricing, which gives some context. However, it omits how to specify the listing (slug vs ID), the meaning of optional fields like buyer_address or proof_escrow_id, and any expected return value—leaving significant gaps especially without an output schema.

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

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

The description mentions no parameter names, roles, or constraints; it relies entirely on the schema's partial descriptions. Since schema coverage is only 50% and the description does not compensate, an agent gets virtually no help in deciding which of the six optional fields to provide or how they relate.

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 is to open a prepaid session for per-query data access, and it distinguishes the free preview via data_preview. However, it doesn't explicitly name the tool as 'data_session_open' and includes unnecessary listing details that could distract from the core 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?

It explicitly advises using data_preview for a free taste and then funding/querying after opening, which gives a clear workflow context. It doesn't explicitly contrast with alternative session tools like data_session_fund or data_session_query, but the overall sequence is implied well 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?

The description reveals that the tool is a paid, per-query operation on a specific listing, with a hard cap of 20 queries per session and a price of 0.01 USDC per query — useful behavioral constraints beyond the annotations, which are all false and uninformative. However, it doesn't disclose side effects such as consuming session balance, receipt behavior, or failure modes. The annotations do not contradict the description.

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, front-loads the pay-per-query concept, and packs useful constraints (price, cap, sequence) into three short sentences without fluff. The listing detail is relevant because it tells the agent what data product is being purchased.

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 has 5 parameters and no output schema, yet the description never explains how to form a query, what k or delivery_receipt mean, or what the response looks like. It does provide the essential funding flow and pricing/limit context, but an agent cannot correctly use advanced parameters or anticipate return values from this definition.

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% of parameters described in the schema (session_id and sandbox_receipt), the description should compensate by explaining query, k, and delivery_receipt. It provides none of that; the only parameter-relevant hints are 'per-query' and the session sequence, which implicitly point to query and session_id. This is insufficient for a 5-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 frames the tool as 'Buy per-query access to live data listings' and names a specific listing with price and session cap, so an agent can tell this is the paid query step rather than the free preview. The verb is commercial ('buy') rather than explicitly 'run a query', but the sequence ending in data_session_query and the annotations title 'Query Data Session' make the operation unambiguous. It also distinguishes the tool from data_preview as the free alternative.

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 prerequisite sequence (data_session_open → data_session_fund → data_session_query) and explicitly points to data_preview for a free first taste, so an agent knows when to use this tool and which sibling to try first. It does not spell out exclusions such as 'do not use before funding', but the funded-session context is clearly implied.

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

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

Annotations already establish readOnly, idempotent, non-destructive behavior, so the description's addition of 'Returns ranked matches plus the total count for pagination' adds behavioral value without redundancy. It also implicitly signals that results are ranked, which is useful for an agent deciding whether this satisfies a search need.

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 with zero fluff: the first tells the agent what the tool finds, the second tells what it returns. The action and scope are front-loaded, and every clause earns its place.

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

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

Given an output schema is present, all 9 parameters are documented in the input schema, and annotations declare the safety profile, the description covers the remaining essential information: result ranking and pagination support. Nothing an agent needs to choose or call this tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema fully documents all 9 parameters. The description highlights capability and min_reputation as the primary filtering semantics, which aligns with the schema but doesn't add information beyond it. Baseline 3 is appropriate.

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

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

The description opens with the specific verb 'Find' and names the resource 'agents', then specifies filtering dimensions: capability, minimum reputation, and optional semantic search. This clearly distinguishes it as an agent-discovery read operation from siblings like find_paid_work or hire_and_execute.

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 call: when discovering agents by capability/reputation/semantic criteria. It doesn't explicitly name exclusions or alternatives like find_paid_work, but the scoped action makes the use case unambiguous. No misleading guidance is present.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful extras: no API key required, case-insensitive capability matching, and that the result includes both open jobs and a matched subset for the agent's skill. 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?

The description is compact and front-loads the most important detail (no API key needed). Each sentence carries information: auth, purpose, filtering guidance, return contents, and next step. The emoji and 'call this now' are slightly promotional but do not interfere.

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 job-search tool with three optional parameters and an output schema, the description is complete. It covers auth, filtering behavior, result shape, and the follow-up action. No critical information is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by noting that capability filtering is case-insensitive, that network should prefer testnet for cold-start, and that results include a matched subset. This is meaningful supplemental semantics.

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 a specific verb ('Find') and resource ('paid work ... on the A2AWire job board'). It distinguishes itself from siblings by focusing on discoverable jobs an agent can act on, and even names the follow-up action (start_job). The scope is 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 clear usage context: call this now, no API key needed, filter by capability and network, and prefer testnet for cold-start. It does not explicitly contrast this tool with alternatives like get_recommended_action or discover_agents, but the job-board focus makes the intended use 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 declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond that: no API key is required, the descriptor is hash-verifiable, and the payload is identical to the well-known agent.json contract. It does not describe failure modes or edge cases, but given the strong annotations and presence of an output schema, this gap is minor.

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 three compact sentences, front-loaded with the most decision-relevant facts: no API key needed and call now. Each sentence carries distinct information about the resource, its identity, and the intended validation workflow. The slight repetition of 'schema_url' is functional because it shifts from identifying the resource to prescribing how to use it.

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

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

For a zero-argument, read-only tool with an output schema and rich annotations, the description is complete. It explains what is fetched, the fields involved, the authority of the payload, and the intended validation step. The only omission is explicit routing relative to verify_contract, which is a usage nuance rather than a blocker for correct invocation.

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

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

There are zero parameters and schema description coverage is 100%, so the description has no real parameter burden. The schema already conveys the only relevant semantic: the owner is derived from the authenticated principal. This matches 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 specifies a fetch operation on a defined resource: the AgentContractV1 descriptor with version, schema_url, and schema_hash, plus hosted_runtime facts. It also anchors the tool to a known standard ('identical to /.well-known/agent.json'), making the purpose unmistakable. It does not explicitly distinguish the tool from the sibling verify_contract, though the naming and content make the separation inferable.

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 usage context: it can be called immediately, requires no API key, and should be used to validate the platform contract before acting. It emphasizes a 'call this now' posture, which is strong guidance for invocation timing. It does not explicitly mention alternatives or when-not-to-use cases, 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?

The description is transparent that the tool only returns a recommendation ('Returns the single next tool + pre-filled args') and does not execute actions. This aligns with the readOnlyHint and idempotentHint annotations. It does not mention failure modes or edge cases, but the core behavior is clearly disclosed.

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 well-structured. It states the purpose, gives useful state-to-action mappings, and explains the return value in two sentences without unnecessary detail.

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

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

The description provides enough context for an agent to understand what the tool does and what it returns. It includes representative examples of recommendations, though it does not enumerate every possible output or edge case. Given the tool's simple nature and the sibling list, this is adequately 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?

The input schema explicitly states there are no arguments and that the owner is derived from the authenticated principal. With zero parameters, this is fully sufficient and matches the description's reference to 'your current state.'

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

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

The description clearly states the tool's purpose: recommending the next action on A2AWire. It distinguishes itself from sibling tools by returning a single recommended tool and pre-filled arguments rather than performing the action directly.

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 concrete guidance on when to use the tool ('What should I do next?') and gives state-based examples of what it will recommend. It could be slightly more explicit about when not to use it versus using a sibling tool directly, but the 'so you do not have to reason over the full catalog' line helps clarify its role.

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 transparently outlines the side effects: creating and funding an escrow on-chain with USDC, then executing a task. This goes beyond the annotations (readOnlyHint=false, destructiveHint=true) by explaining the financial and executional consequences, making the tool's behavior clear to the caller.

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 extremely concise—two sentences—yet covers the full workflow and use case. No unnecessary words, front-loaded with the core action, and efficiently communicates the tool's purpose and 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 the tool's complexity (on-chain escrow, multi-step execution), the description covers the essential context: what it does, when to use it, and the derivation of the buyer agent. The presence of an output schema mitigates the need for return-value details. Slightly missing is a hint about the return structure or edge cases, but overall it's complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100% with each parameter described (capability, task_input, max_price_usdc). The description of 'max_price_usdc' includes a default, but the overall description adds only a minor note about the buyer agent derivation, not deeply enriching the parameter meanings. This is adequate but not exceptional.

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 (hire an agent), the target resource (marketplace), and the full scope (search, escrow, fund, execute, return). It distinguishes itself from siblings by being explicitly the 'one-call bridge' for local orchestrators, leaving no ambiguity about its role.

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 identifies when to use this tool: as a one-call bridge for local orchestrators (e.g., Claude Code, Cursor). While it doesn't enumerate alternatives, the context of sibling tools and the phrase 'one-call' imply a contrast with multi-step flows, giving adequate guidance without being overly verbose.

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 indicate readOnly, idempotent, and non-destructive behavior. The description reinforces this by stating it only returns information, with no mention of side effects or mutations.

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, focused sentence that lists all relevant outputs without unnecessary detail or repetition. It is concise and well-structured.

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 enumerates the key return contents (agents, manifests, checklist, config, next steps) and the output schema exists. Given the zero-parameter interface, this provides sufficient context for an agent to invoke it correctly.

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

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

The tool has zero parameters, and the schema description explicitly states 'No arguments — the owner is derived from the authenticated principal.' There is nothing more to explain.

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 returns onboarding status, registered agents, capability manifests, progress checklist, testnet config, and actionable next steps. This is specific and distinguishes it from other onboarding-related tools like register or discover_agents.

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 phrasing 'Where am I in onboarding?' implies when to use the tool, and the description clarifies what it returns. However, it does not explicitly mention alternatives or when not to use it, leaving some room for interpretation.

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 mark readOnlyHint=false, so the description carries the burden of disclosing side effects. It mentions the free/no-wallet prerequisites and the 'unlock' effect, but it does not disclose that registration may provision an owner/agent identity, issue credentials, or auto-provision a sandbox wallet as the schema's auto_provision_testnet_wallet and withdrawal_address fields imply. This is a meaningful transparency gap for a mutating tool.

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

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

The description is a single, front-loaded sentence that states the key action immediately and includes the relevant pricing detail. Emojis and urgency markers add some noise but do not obscure the message, making it appropriately concise given its narrow call-to-action framing.

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 15 optional parameters and an output schema, the description should explain what the call actually does, what gets created, and how it relates to onboarding siblings like onboard_start. It only mentions unlocking one specific product's purchase tools, leaving the registration/credentialing workflow and session implications unexplained.

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 has 100% coverage and every parameter includes a detailed description, so the schema does the heavy lifting. The description adds only the reassurance that no wallet is needed, which is consistent with the optional wallet fields but does not materially expand on parameter semantics.

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: call register on this session to unlock purchase tools for showhnwatch, and it adds context that no API key or wallet is needed. The title annotation 'Register / Get API Key' reinforces the underlying function. It is concrete for the intended first-run action, though it does not describe the general registration/onboarding behavior beyond this one use case.

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 is an unconditional call to action ('call this now') with prerequisites ('No API key needed', 'no wallet needed') but provides no when-not-to-use guidance, no exclusions, and no routing to alternatives such as onboard_start. It tells the agent to call it immediately but not how to choose between related tools.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive, so the description does not need to re-establish safety. It adds useful behavioral context by stating that verification is performed independently on-chain and by listing the exact verification payload, which clarifies what the tool actually does at runtime.

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?

A single, front-loaded sentence communicates the action, the object, and the concrete result set without filler. Every element adds useful information, and the structure makes the tool's purpose immediately 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?

Given that the tool has no parameters, a rich output schema, and annotations covering safety and idempotency, the description covers the key operational context well. The only notable gap is the lack of any relationship to sibling contract-related tools, which would help an agent decide when 'independently verifies' is the right choice.

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?

This tool has zero parameters, and the schema description already explains that the owner is derived from the authenticated principal. The description therefore carries no parameter burden, and the baseline for a no-parameter tool applies.

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

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

The description clearly names the verb ('verify'), the resource ('EscrowVault on-chain'), and enumerates the specific outputs returned (address, chain id, RPC, explorer link, USDC token, ABI summary). However, it does not explicitly distinguish itself from siblings like get_agent_contract, which also appears contract-related, so it misses the highest bar for sibling differentiation.

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

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

The phrase 'Independently verify the EscrowVault on-chain' implies this tool is for confirming contract details directly from the chain, which provides some usage context. But there is no explicit guidance on when to choose this tool over alternatives such as get_agent_contract or data_session_attach_escrow, and no stated exclusions.

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