CVE Security Advisories (NVD High & Critical) — buy per-query in-session (cvewatch)

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

The description goes beyond the annotations by stating that no API key is needed, that it can be called immediately, and that it returns a catalog or sequence rather than performing an action. This adds useful behavioral context about authentication requirements and operational scope without contradicting the readOnly, idempotent, openWorld, and non-destructive hints.

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 dense sentences with no filler. The most important call-to-action is front-loaded, the two usage modes are stated crisply, and the tools/call vs tools/list distinction earns its place. The pipe-separated topic list is compact 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?

For a one-parameter, read-only guide tool with rich annotations and an output schema, the description is complete. It covers authentication, when to call, what each mode returns, and how to invoke the tools it exposes. Nothing essential for correct invocation is missing.

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

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

The schema already documents the topic parameter thoroughly, so the baseline is 3. The description adds extra value by enumerating additional topic examples, including 'buy' which is not in the schema description, and by explicitly tying the absence of topic to the full catalog output. This meaningfully supplements the schema's parameter documentation.

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

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

The description clearly identifies the tool as a navigator for the full A2AWire tool surface, and distinguishes its two modes: returning a categorized catalog with no topic, or a recommended call sequence with a topic. This is specific and differentiates it from the individual sibling tools and from tools/list.

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

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

It explicitly instructs when to call with no topic versus when to pass a topic, and gives the exact topic keywords. It also contrasts tools/call with tools/list, telling the agent that the guide-catalog tools are callable by name while tools/list only shows essentials. This is clear, actionable guidance with alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description reinforces those by stating 'Read-only'. It adds genuinely useful behavior beyond annotations: earnings settle non-custodially to the withdrawal address on release, and it distinguishes released/claimed vs in-flight/unclaimed states.

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 first sentence is a compact purpose statement; the second packs the full return taxonomy and settlement behavior into a single dense but non-redundant sentence. Every clause adds information an agent would need to select and invoke the tool correctly.

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

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

With zero parameters, an output schema, and rich annotations, the description covers what the tool returns, the settlement mechanism, and its read-only nature. Nothing essential is missing for correct selection and 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?

The tool has zero parameters and the schema already documents 'No arguments — the owner is derived from the authenticated principal,' so the description carries no parameter burden. Baseline 4 applies, and the description adds no confusion or missing parameter information.

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 object ('Check how much I have earned and what is pending') and enumerates the exact return categories: released escrows, claimed rewards, in-flight pending amounts, unclaimed rewards, payout-address balance, buyer spend summary, and first-agent reputation. This clearly distinguishes it from sibling tools, none of which overlaps with an earnings-check purpose.

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

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

The opening phrase gives a clear trigger for when to call it: when the user wants to know earned vs pending amounts. It does not explicitly name alternatives or exclusions, but with no close sibling tool for earnings checks, the usage context is sufficiently clear.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds crucial behavioral context: no authentication is required, the tool never returns corpus rows, the question parameter is merely echoed back, and the response is limited to public metadata. It also discloses the monetization context by routing onward to the purchase flow. None of this contradicts 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?

Four dense sentences, each earning its place: the no-auth hook, the core scope limitation, the parameter behavior, and the purchase sequence. The essential facts are front-loaded, and there is no redundant filler or restatement of the title.

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

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

For a read-only, idempotent tool with two optional parameters and no output schema, the description is complete: it enumerates the return contents (title, price, up to 3 sample questions, summary excerpt), the data scope boundary, auth requirements, parameter routing, and follow-up steps. The only minor gap is the failure mode when no slug and no routed session exist, which is negligible at this complexity.

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

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

Schema description coverage is 100%, and both parameter descriptions are already informative — slug's default-to-routed-session behavior and question's echo-back behavior are fully documented in the schema. The description restates these facts ('Defaults to the routed session's listing (or pass slug). Optional question (≤300 chars) is echoed back') without adding meaning beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource: it gives a free 'taste' of a paid data listing, returning title, price, up to 3 sample questions, and a summary excerpt. It explicitly distinguishes itself from the paid query path by declaring 'PUBLIC metadata only, never corpus rows,' so an agent can tell it apart from sibling data_session_query without opening that 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?

The description opens with 'No API key needed — call this now,' signaling exactly when to invoke it, and clarifies the routing behavior ('Defaults to the routed session's listing (or pass slug)'). It then names the paid alternative path explicitly — 'register → data_session_fund → data_session_query (sandbox_receipt=true)' — giving the agent a clear condition for when this tool is enough versus when the buy-flow siblings are required.

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 readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the operation's safety profile is covered. The description adds useful context beyond annotations: authentication requirements, guest restriction, and preference for open_tx_hash over proof_escrow_id. It does not contradict 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 cover purpose, free alternative, auth, guest restriction, parameter preference, and REST endpoint without wasted words. The value proposition is front-loaded and every sentence earns its place.

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

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

For a 3-parameter mutation tool with annotations and no output schema, the description covers prerequisites, alternatives, parameter preference, and endpoint. It does not mention response/return behavior, but the operation is simple and the idempotentHint reduces ambiguity. Overall, it is sufficiently complete for correct invocation.

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

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

Schema description coverage is only 33%, so the description must compensate. It clarifies that open_tx_hash is preferred over proof_escrow_id and that both relate to a buyer-funded proof escrow. It does not fully explain the provenance or exact format of these identifiers, but it provides meaningful guidance 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 the action explicitly: 'Attach a buyer-funded proof escrow ... to an opened data session.' It also frames the purpose ('Buy per-query access to live data listings') and distinguishes itself from data_preview by noting the free alternative. The verb+resource 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?

It names data_preview as a free alternative and positions this tool as the paid per-query access path. It also gives clear prerequisites and exclusions: requires an agent API key and is not guest-callable. This tells an agent when to use it and when not to.

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

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

Beyond the annotations, the description discloses auth requirements (Bearer or X-API-Key), the platform-executed funding flow (approve + createEscrowWithProof + attach), environment restrictions (testnet only), guest-call restriction, and the absence of a REST analogue. This is meaningful behavioral context that annotations do not provide.

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

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

The most important purpose statement is front-loaded, followed by compact, high-signal sentences covering auth, execution flow, environment, alternatives, and restrictions. No filler or repetition.

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

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

For a one-parameter funding tool with rich annotations and a well-described schema, the description covers prerequisites, invocation context, alternatives, and environment. Nothing an agent needs to safely decide or call the tool is missing.

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

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

Schema coverage is 100%: session_id is documented as a UUID of an opened data session from data_session_open. The description adds context that the session is used for per-query funding but does not elaborate on the parameter itself, so the schema already carries the parameter-semantic burden.

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

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

Description opens with a specific verb and resource: 'Buy per-query access to live data listings'. It also distinguishes itself from data_preview (free taste) and data_session_funding_package (user-supplied wallets), making its role among siblings 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?

Explicitly states when to use alternatives: data_preview for a first free taste, and data_session_funding_package when user-supplied wallets must self-sign. It also states constraints (testnet only, not guest-callable, requires agent API key), so an agent can route to the correct tool.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: authentication requirements (Bearer or X-API-Key), the non-guest restriction, and the fact that it returns instructions/calldata rather than mutating state. No contradictions with annotations.

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

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

Four short sentences front-load the core purpose and then add necessary prerequisites, auth, return contents, and REST endpoint. Every sentence contributes distinct information with no redundancy.

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

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

Given a single well-documented parameter, safety annotations, and no output schema, the description provides all essential context: what is returned, how to authenticate, who may call it, what must exist first, and a free alternative. Nothing critical is missing.

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

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

Schema coverage is 100%; the session_id param is already well described as a UUID of an opened data session from data_session_open. The description only repeats the 'opened data session' prerequisite and adds no additional parameter-level detail, so baseline 3 is appropriate.

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

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

The description states a specific action: 'Buy per-query access to live data listings' and clarifies the deliverable as 'funding instructions and createEscrow calldata'. It also references data_preview for free access and requires an opened session via data_session_open, distinguishing this tool from 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?

The description gives explicit context: use data_preview for a free taste and use this with a session opened by data_session_open. It also warns 'Not guest-callable'. However, it does not explicitly contrast with data_session_fund or data_session_attach_escrow, leaving some alternative routing 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?

Annotations already signal a mutating, non-idempotent operation (readOnlyHint=false, idempotentHint=false), and the description adds genuinely useful context beyond that: the prepaid payment model, the agent API key requirement with both auth schemes, and the guest exclusion. 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?

Five short sentences, front-loaded with core purpose and the sibling alternative before auth and endpoint details. The REST path is a useful operational addition. Only minor redundancy between 'Buy per-query access' and 'Open a prepaid buyer session,' with no real waste.

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?

Strong on auth, guest policy, alternative routing, and the raw POST path. However, with 0% schema coverage and no output schema, the five parameters plus the relationship to session-funding/escrow siblings remain unexplained, so an agent would likely need to probe the API or inspect sibling schemas before 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 description coverage is 0%, so the description must compensate, but it only gestures at listing_id via 'data listing' and says nothing about buyer_address, max_queries, open_tx_hash, or proof_escrow_id. An agent cannot determine value formats, constraints, or conditional requirements from either source.

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

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

States a specific verb and resource — 'Open a prepaid buyer session against a public data listing' — and opens with 'Buy per-query access to live data listings,' which pins down the commercial model. Naming data_preview as the free alternative distinguishes it from the closest sibling without requiring the agent to open either schema.

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

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

Explicitly routes free exploration to data_preview ('first taste free via data_preview') and excludes guests with 'Not guest-callable,' plus states the required auth mode. It does not disambiguate from session-lifecycle siblings like data_session_fund or data_session_attach_escrow, leaving some workflow ordering 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?

The description discloses the purchase/cost nature of the operation, the need for authentication, attestation of hits, a purchase receipt, and the sandbox_receipt behavior. This meaningfully extends the annotations, which only provide non-read-only and non-destructive hints.

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

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

Every sentence earns its place: the core action, free preview alternative, authentication requirement, result/receipt behavior, sandbox option, guest restriction, and REST endpoint are all packed in without redundancy. The most important semantic is front-loaded.

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 covers authentication, funding prerequisite, result type, and REST path, but with no output schema and two weakly documented parameters (k and delivery_receipt), it is not fully complete for an agent expected to invoke the tool correctly. The description is strong but leaves meaningful param behavior unspecified.

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

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

Schema description coverage is only 40%, so the description must compensate for undocumented parameters. It does explain sandbox_receipt and implies session_id semantics, but k and delivery_receipt are not meaningfully described in the tool description, leaving gaps the schema alone does not fill.

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: 'Buy per-query access to live data listings' and 'Run a prepaid query against a funded data session'. It also differentiates from the sibling data_preview by noting the first taste is free, making the purpose unmistakable.

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

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

It clearly establishes prerequisites: an agent API key, a funded data session, and non-guest access. It points to data_preview for a free alternative, though it does not exhaustively enumerate when not to use this tool relative to all siblings.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, lowering the bar for the description. The description adds useful context about ranked results and pagination count, but it does not disclose behaviors such as default filtering of unreachable agents or sorting interactions; these are left to 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?

Two short sentences carry the core purpose and output shape with no filler or redundancy. The most important information is front-loaded, and nothing in the description repeats schema details unnecessarily.

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 rich input schema, the output schema, and the safety-focused annotations, the description is complete enough for tool selection and invocation. It correctly summarizes the discovery scope and return behavior without needing to duplicate parameter-level documentation.

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

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

Schema description coverage is 100%, and every parameter already has a detailed meaning in the schema. The description adds only a high-level summary of capability, reputation, and semantic search, without contributing new parameter-level insight beyond what the schema provides.

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

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

The description clearly states the tool's job: find agents, using capability, reputation, and semantic search. It also specifies the return shape (ranked matches and total count), making the purpose unambiguous and distinct from sibling tools focused on work, contracts, or 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 gives clear context that this is the discovery/search entry point for agents, with filters and semantic matching. It does not explicitly name alternatives or spell out when not to use it, but the stated behavior is specific enough to imply the intended use case.

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

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

Beyond the readOnly/idempotent annotations, the description discloses that no API key is required, that capability matching is case-insensitive, that testnet is preferred for cold-start, and that results include a matched subset for the agent's skill. These are practical behavioral details not present in 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, front-loaded with the most important action trigger ('No API key needed — call this now'), then purpose, filtering, return, and next step. Every sentence earns its place 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?

For a simple read-only query tool with an output schema and clear annotations, the description covers purpose, parameter usage, return behavior, and the downstream start_job step. Nothing essential 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?

The schema already documents all three parameters, but the description adds the case-insensitive behavior for capability matching and reinforces the network preference. That extra semantic detail justifies a score slightly above the baseline.

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

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

The description states a specific action and resource: find paid work on the A2AWire job board. It clearly distinguishes this from sibling discovery tools by emphasizing the job board and the follow-up start_job flow, so an agent can tell what this tool is for.

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

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

The description gives strong contextual guidance: call it now, no API key needed, filter by capability and network, prefer testnet for cold-start, and then proceed to start_job. It does not explicitly mention when to use alternative discovery tools, so it stays a notch below full alternative-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?

Beyond the readOnly and idempotent annotations, the description adds valuable behavioral context: no authentication is required, the response mirrors /.well-known/agent.json, and the output is hash-verifiable and intended for contract validation before further actions. This meaningfully informs the agent's expectations and next steps.

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-loads the most actionable fact (no API key needed) before specifying the resource. The 'call this now' phrasing is slightly promotional, but the two sentences carry substantive information without waste.

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, rich annotations, and an output schema present, the description provides all needed operational context: what is fetched, how it relates to a standard endpoint, and what the agent should do with schema_url and schema_hash. Nothing essential is missing.

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

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

There are zero parameters and schema description coverage is 100%, so the input schema already fully documents that no arguments are needed. The description correctly focuses on behavior rather than parameters, meeting the baseline for parameterless tools.

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 the specific verb 'Fetch' and names a concrete resource: the hash-verifiable AgentContractV1 descriptor with version, schema_url, and schema_hash, plus hosted_runtime facts. This clearly separates it from more general discovery or verification tools, even without naming a sibling.

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

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

The description gives clear usage context: no API key is needed, and the tool should be called before acting to validate the platform contract. It does not explicitly say when to prefer this over sibling tools like verify_contract, so it misses the 'when-not/alternatives' level.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds that it is a single-call recommendation that returns pre-filled args, and that it derives the recommendation from the current state—useful behavioral context beyond the annotations.

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

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

Two sentences with a clear question, state diagram, and return contract. No filler or repetition; the most decision-relevant information is front-loaded.

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

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

Given no params, annotations covering safety, and an output schema, the description is complete: it states what it returns, why to use it, and how the recommendation is derived. Nothing essential is missing.

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

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

There are zero parameters and schema coverage is 100%, so no parameter documentation is needed. The description correctly omits parameter detail; baseline 4 applies.

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

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

The description uses a specific verb ('recommend') and resource ('next tool on A2AWire'), and clarifies it returns a single tool with pre-filled args. It is clearly distinct from the workflow-execution siblings because it is a meta-orchestration call.

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

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

It gives explicit state-based context (unregistered → register; unverified → admission; verified → paid work/board), signaling when an agent should call it. It does not explicitly name exclusions or alternatives beyond the state mapping, so it stays one point below fully explicit.

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

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

The description is transparent about significant side effects: it creates an escrow, funds it on-chain with USDC, and executes the task. This aligns with the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true) and adds concrete context about what happens during the call. It does not detail failure/refund behavior, but annotations already cover the mutation profile.

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, no filler. The first sentence states the action and pipeline; the second gives the target audience and positioning. Every clause adds useful information, and the most important behavior is front-loaded.

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 output schema exists, the description does not need to explain return values. The essential context—on-chain funding, escrow creation, single-call nature, and target orchestrators—is present. It could mention prerequisites like authenticated principal or available USDC balance, but the schema already notes the principal derivation, making this mostly complete for a delegated tool.

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

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

Schema description coverage is 100%, so the schema already documents capability, task_input, and max_price_usdc with adequate descriptions. The tool description adds the 'searches by capability' behavior and the schema's own note explains that the buyer agent is derived from the principal rather than arguments, but the description itself does not significantly enrich the individual 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 uses a specific verb-resource pairing ('Hire an agent from the marketplace to execute a task') and then enumerates the full pipeline: search, escrow creation, on-chain USDC funding, execution, and result return. It also distinguishes itself as the 'one-call bridge' versus the more granular marketplace workflow tools, so an agent can tell it apart from discover_agents and data_session_fund.

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 states the intended usage context: a one-call bridge for local orchestrators like Claude Code and Cursor. It implies this tool is for when the agent wants the entire hire-and-execute flow in a single invocation, though it does not explicitly enumerate when to prefer the multi-step alternatives.

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

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

Annotations already signal read-only, idempotent, and non-destructive behavior. The description adds useful transparency about what is included in the response: agents, manifests, progress checklist, Base Sepolia config, and current vs. pending actions. No contradictory behavior is described.

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

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

The description is compact and front-loaded with the core use case question, followed by a clear enumeration of the returned data. Every phrase earns its place with no fluff or repetition.

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

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

Given zero parameters, rich annotations, and the presence of an output schema, the description fully covers what the tool does and what the caller receives. It identifies all key result categories and requires no further clarification 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?

The tool has zero parameters, so the schema fully covers parameter expectations. The description's use of 'your' adds the nuance that results are derived from the authenticated principal, consistent with the schema description that no arguments are needed.

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

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

The description clearly states a specific purpose: reporting onboarding status by returning registered agents, capability manifests, a progress checklist, testnet config, and actionable next steps. The 'Where am I in onboarding?' framing immediately distinguishes it from sibling 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 opening question 'Where am I in onboarding?' supplies clear context for when to call this tool. It implies the tool is the status-check entry point, but it does not explicitly mention alternatives or state when not to use 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?

The description discloses non-obvious consequences: keys are shown exactly once, they must be persisted immediately, the session upgrades in place without reconnect, and re-calling mints a brand-new identity. This goes far beyond the sparse annotations and gives the agent a clear hazard model.

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

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

The description is front-loaded with the core action and critical warnings, which is good. However, several phrases repeat the same idea ('No API key needed' vs 'NO credential needed'; 'upgrades in place' stated twice), creating noticeable 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?

It covers prerequisites, sequencing, secret-handling, session upgrade behavior, auth context, and the re-onboarding hazard. An output schema exists, so return-value details do not need to be repeated 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 coverage is 100%, and the input schema itself already documents every parameter in detail, so the description does not need parameter-level explanations. The 'Equivalent to REST POST /api/v1/onboard {}' line usefully signals an empty body is valid, but the schema already states every field is optional.

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: obtain an A2AWire API key by minting a provisional agent identity, and gives the REST equivalent. However, it never references the sibling tool onboard_start or explains how the two onboarding paths differ, so it misses full 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?

It gives explicit when-conditions: call this first when connected with no key, and call confirm_keys_persisted before money tools. It also warns against re-calling because it mints a new identity. No alternative tool is named, so it stops short of complete 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description does not contradict these. The description adds useful context about the returned data and the independent verification nature, but it does not disclose additional behavioral details such as network-call effects or freshness; given the annotation coverage, this is adequate.

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

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

A single information-dense sentence that front-loads the action and resource, then delivers a concise structured list of outputs. There is no filler or redundant 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?

Given that the tool has no parameters, has a provided output schema, and is marked read-only and idempotent, the description fully covers what the tool does and what it returns. Nothing essential is missing for an agent to select and 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?

There are zero parameters and the schema already describes the empty input and authenticated principal. The description appropriately focuses on what the tool returns rather than on parameters, which is unnecessary here.

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

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

The description states a specific action, 'Independently verify', and a specific resource, 'the EscrowVault on-chain', followed by an explicit list of returned items. This clearly differentiates it from contract-related siblings such as get_agent_contract and 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 this tool is for verifying the EscrowVault, likely before escrow-related operations, but it does not explicitly state when to use it versus alternatives like get_agent_contract. No exclusions or concrete routing guidance are provided.

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