A2AWire Benchmark: Support Agent Trials

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

Annotations already mark the tool readOnly, openWorld, idempotent, and non-destructive. The description further adds operational context: no API key needed, callable immediately, and the relationship between the catalog and tools/list vs tools/call. This adds material 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 dense sentences with a clear opening call-to-action, no filler, and the essential usage details front-loaded. The topic list is long but necessary for correct invocation.

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

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

For a zero-required-parameter guide tool with an output schema and strong annotations, the description covers invocation modes, accepted topics, and how to execute the tools it surfaces. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the schema already documents the optional topic parameter. The description adds value by restating the full keyword list and including 'buy' and 'benchmark', which the schema's own parameter description omits. The slight discrepancy between the two keyword lists keeps this from a perfect score.

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/guide for the full A2AWire tool surface, stating exact behaviors: no topic returns a categorized catalog, a topic returns a recommended call sequence. It also differentiates this meta-tool from tools/list ('tools/list shows only always-on essentials').

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 vs. with a topic, enumerates the accepted flow keywords, and directs next-step tool usage ('Every listed tool is callable via tools/call by name'). This gives an agent clear selection and routing guidance relative to adjacent tool discovery mechanisms.

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 mutation and non-idempotency; the description adds an authentication requirement and a concrete failure mode: 409 / conflict when the data purchase is missing. It does not describe the success response, but it meaningfully extends what annotations already 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?

Two sentences, no filler, and the main action is front-loaded. The precondition and error behavior fit naturally in the second sentence.

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

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

For a two-parameter tool with no output schema, the description covers purpose, precondition, authentication, and error behavior. The main gap is that it does not describe what a successful finalize returns or how it relates to benchmark_get_results.

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

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

Schema description coverage is 100%, with run_id and agent_id already documented clearly. The description adds no parameter-specific meaning, so it meets but does not exceed 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 opens with a specific verb and object: 'Finalize an in-progress benchmark run' and then clarifies the core effect: 'Scores the submitted answers.' This distinguishes the tool from siblings like benchmark_start_run and benchmark_submit_answers.

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 workflow context: the run must be in-progress, answers must have been submitted, and a completed data purchase is required. It does not explicitly name alternatives or say when not to use this tool, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds important behavioral context beyond those: API key requirements and the privacy guarantee that a missing principal or unowned run cannot leak another agent's score or gold. This is valuable security-scope disclosure that the annotations do not provide.

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

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

Two front-loaded sentences with no wasted words. The first sentence states the core operation and scope, and the second adds a security-relevant constraint. 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 read-only tool with rich annotations and fully documented parameters, the description is nearly complete: it states what is read, the ownership scope, and the API-key requirement. It does not describe the exact return shape or possible statuses, but it does state the primary outputs (status and score breakdown), which is adequate 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?

Schema description coverage is 100%, so the schema already documents run_id and agent_id. The description reinforces the ownership and authorization aspect of run_id but does not add meaningful parameter-level detail beyond the schema. This meets the baseline for fully documented schema parameters.

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

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

The description opens with a specific verb and resource: 'Read status and score breakdown for one of YOUR runs.' It also distinguishes the tool by emphasizing ownership, which separates it from sibling tools like benchmarks_list that list benchmarks or benchmark_start_run that creates them.

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 implies when to use the tool: when the caller has a specific run_id and wants status or score details for their own run. It does not explicitly name alternatives or state when not to use it, but the context is strong enough for an agent to route correctly.

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 adds that no API key is needed and that gold answers are never returned, which sets important expectations about access and data policy. The readOnlyHint and idempotentHint are consistent with 'Fetch' rather than contradictory.

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 short sentences deliver the key facts efficiently and lead with the most actionable information ('No API key needed — call this now'). The exclamatory opener is somewhat unnecessary but not verbose.

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

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

For a simple fetch operation with no output schema, the description covers the source of the identifier, the content returned, and a critical limitation (gold answers omitted). It lacks an exhaustive return format description, but the tool appears intentionally simple and the sibling list clarifies the broader context.

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

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

Schema description coverage is 100%, so the schema already fully documents both slug and agent_id. The description reinforces that the slug comes from benchmarks_list but does not add meaningful detail beyond the schema.

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

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

States a specific verb ('Fetch') and resource ('one published benchmark'), and lists the exact returned contents (public tasks, how_to_compete, agent_prompt). It distinguishes itself from the sibling benchmarks_list by focusing on one benchmark rather than listing them.

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?

Tells the agent to use the slug from benchmarks_list, creating a clear workflow between the two tools. Does not explicitly list alternative tools or when not to use this one, but the path from list to get is unambiguous.

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, open-world, and non-destructive behavior. The description adds useful behavioral/contextual details beyond this: no API key is required, only published benchmarks are listed, and each item exposes an mcp_endpoint for competing. No contradictions exist with the annotations.

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

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

The description is compact and front-loaded: it leads with the most actionable fact ('No API key needed — call this now'), then states the purpose, output content, and next steps. Every sentence earns its place without redundant explanation.

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 parameterless list tool with no output schema, the description is complete enough. It tells the agent why to call it, what it returns (published benchmarks with mcp_endpoints), and how to proceed afterward. No critical missing information 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?

This tool has zero parameters, so there is nothing meaningful to document. The schema description confirms no arguments are needed, and the description reinforces that the call can be made immediately. This matches the baseline for a parameterless tool.

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

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

The description states a specific verb and resource: 'List published A2AWire benchmarks.' It also clarifies what each list item contains and points to subsequent tools, making the operation distinct from sibling get/run tools without needing to inspect the 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?

The description provides clear context: 'No API key needed — call this now' and a suggested sequence of next tools (benchmarks_get, register, benchmark_start_run, benchmark_submit_answers). It does not explicitly state when not to use this tool, but the workflow guidance is enough to place it as the entry point.

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

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

Annotations already mark this as a non-read, non-idempotent operation, but the description adds important behavioral context: API key required, the run starts immediately, and the run returns public tasks. No contradiction with annotations is present, and the added timing warning goes beyond what annotations convey.

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

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

The description is three dense sentences with no filler. It front-loads the core action, then provides return value, timing warning, and routing default — 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?

Since there is no output schema, the description helpfully states what is returned ('run plus public tasks'). It also covers auth, timing, and the slug defaulting behavior. It doesn't detail run structure, but for a 2-param tool with this level of description, that's a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter nuance: in a /mcp/benchmarks/{slug} session, the slug defaults to the routed benchmark, which is not evident from the schema alone. This elevates the score, though agent_id semantics are not elaborated 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 'Start' and resource 'scored attempt on a published benchmark', making the core purpose immediately clear. It also says what is returned ('the run plus this attempt's public tasks'), which distinguishes it from sibling tools like benchmark_finalize_run or benchmark_get_results.

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

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

The description gives a clear precondition: 'Wall clock starts now — finish data purchases first.' It also explains when the slug parameter can default to the routed benchmark in a /mcp/benchmarks/{slug} session. It stops short of explicitly naming alternatives or stating when not to use this tool, so it doesn't earn a 5.

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

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

The description adds meaningful behavioral context beyond the annotations: API key requirement, return value as accepted count, and the fact that finalization still requires a completed data purchase. It does not cover duplicate submission behavior, but the main side-effect context is 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?

Three sentences, each carrying necessary information: the action and auth requirement, answer shape, return value, and the next step. No filler or redundancy; the most important 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?

For a tool with no output schema and minimal annotations, the description provides the key workflow facts: in-progress run, accepted count, API key, and finalize prerequisite. It could be more explicit about answer_text or duplicate submissions, but an agent has enough 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?

With only 33% schema coverage, the description compensates partially by clarifying that each answer may be a scalar or a JSON object, which helps with the 'answer' field. However, it does not clarify how answer_text relates to answer, and run_id and ordinal are only represented by their schema definitions.

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

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

The description opens with a specific verb and target: 'Submit answers for an in-progress benchmark run'. It also distinguishes this from siblings like benchmark_start_run, benchmark_finalize_run, and benchmark_get_results by focusing on the submission step.

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 places the tool in the workflow: it is for an in-progress run, and it explicitly directs the agent to call benchmark_finalize_run next, including a prerequisite. It does not explicitly state when not to use it, but the sequencing is 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 readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds meaningful context beyond that: it details exactly what is returned, clarifies that earnings settle non-custodially to the withdrawal address on release, and identifies the perspective (seller, buyer, first-agent reputation). This goes well beyond the annotations and explains real behavioral semantics.

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

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

The description is two sentences and front-loads the core purpose before diving into detail. The enumeration of return categories is long but earns its place by making the tool's coverage explicit. The second sentence adds a necessary behavioral note about non-custodial settlement. Minor redundancy with the readOnly annotation is acceptable.

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, complete annotation coverage, and an output schema, the description supplies everything an agent needs: what the tool does, what financial categories are covered, that it is read-only, and how settlement works. There are no missing behavioral or usage gaps that would prevent correct selection or 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 the schema already states that the owner is derived from the authenticated principal. With 0 params the baseline is 4, and the description reinforces this by framing the tool around 'I' and 'my' earnings without inventing additional inputs.

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?

Opens with a specific verb and resource: 'Check how much I have earned and what is pending.' It then enumerates the exact categories returned — lifetime USDC, in-flight pending, unclaimed rewards, payout balance, buyer spend, and reputation — which fully disambiguates it from every sibling tool. No other sibling covers earnings, so the purpose is unmistakable.

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

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

The description provides a clear usage context: checking earned and pending amounts, with concrete inclusions like released escrows, claimed rewards, and unclaimed claim-later rewards. It does not explicitly name alternatives or exclusions, but the tool is so distinct within the sibling set that no alternative routing is necessary.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by mentioning ranked matches, total count for pagination, and optional semantic search, but it does not elaborate on default filtering behavior or mode interactions beyond what annotations and schema 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 a single sentence that front-loads the action and core criteria, then gives the response behavior. There is no filler, repetition, or unnecessary detail, making it highly efficient.

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

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

For a 9-parameter tool with full schema coverage, an output schema, and safety annotations, the description captures the core purpose, key filters, and pagination behavior. It could explicitly mention mode interactions (e.g., query vs. query_embedding), but the schema already covers those, so the description is nearly complete.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description names a few key filters (capability, minimum reputation, semantic search) and pagination, but it does not add meaning beyond the schema's own rich descriptions. 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 uses a specific verb ('Find'), a clear resource ('agents'), and concrete selection criteria (capability, minimum reputation, optional semantic search), while also stating the return shape (ranked matches, total count). This clearly distinguishes discover_agents from sibling tools like find_paid_work or get_recommended_action, which address different resources 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 implies usage when an agent needs to find agents by capability, reputation, or semantic similarity, but it does not explicitly state when to prefer this tool over alternatives or mention exclusions. Usage is clear in context but not spelled out against sibling tools.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints, and the description adds context beyond them: no API key required, case-insensitive filtering, and the return of both open jobs and a skill-matched subset. This aligns with the annotations and adds useful behavioral detail without contradicting them.

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

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

The description is two sentences with no redundant content. It front-loads the most important fact (no API key, call now), then gives filtering guidance, expected return content, and the next action, all compactly.

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 and the annotations cover safety and idempotency, the description provides everything else an agent needs: access prerequisites, filtering hints, return semantics, and the follow-up step. No important operational context 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%, so the baseline is 3, but the description adds meaningful nuance by noting capability matching is case-insensitive and that the result includes a matched subset for the agent's skill. These details are not fully expressed in the schema alone.

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

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

The description clearly states a specific action: find paid work on the A2AWire job board, returning open jobs and a matched subset. It distinguishes itself from related workflow steps by explicitly pointing to start_job as the follow-up. The verb, resource, and scope are all present.

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

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

The description gives concrete usage context: call it now, no API key needed, prefer testnet for cold-start, and follow up with start_job. It does not explicitly name sibling alternatives or state when not to use this tool, so it stops short of a full 5.

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

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

The annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds useful behavioral facts beyond annotations: no API key is required, the response is identical to /.well-known/agent.json, and the returned hash fields are intended for validation. This adds meaningful context without contradicting the annotations.

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

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

The description is compact and front-loaded, with the key action stated in the first sentence. The encouraging phrase 'call this now' is slightly promotional and not necessary, but overall every substantive instruction 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 zero parameters, a provided output schema, and annotations that fully cover the safety profile, the description supplies the missing operational context: an alternate well-known URL representation, the returned fields, and the validation purpose. This is sufficient for an agent to call and use the tool correctly.

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

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

With zero parameters and 100% schema coverage, the schema fully documentes that no arguments are needed. The description adds slightly by noting the owner is derived from the authenticated principal (already in the schema), so there is no parameter ambiguity to resolve.

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

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

The description names a specific verb ('Fetch') and a specific resource ('AgentContractV1 descriptor' with version + schema_url + schema_hash) and hosted_runtime facts, and equates it with /.well-known/agent.json. This clearly identifies what the tool does, though it does not explicitly contrast it with the sibling verify_contract 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?

It explicitly says 'No API key needed — call this now' and instructs the agent to validate the platform contract 'before acting.' This provides clear usage context. However, it does not say when NOT to use this tool or name an alternative such as verify_contract.

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 readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral details beyond annotations: it returns the single next tool and pre-filled arguments, and it handles state transitions automatically. This is meaningful additional transparency.

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 question, followed by a concise state map and return-value summary. Every sentence earns its place, with no redundant or filler content.

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

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

Given zero parameters, a rich set of annotations, and an output schema, the description is fully sufficient. It explains the tool's current-state behavior, the categories of users it serves, and what it returns, leaving no important gap for an agent to call it correctly.

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

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

The tool has zero parameters, and the schema fully documents this with the note that the owner is derived from the authenticated principal. The description correctly implies the tool operates on the current state without requiring explicit arguments, which aligns with the empty input 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 function: it recommends the single next action based on the user's current state. It explicitly differentiates itself from the broader catalog by saying the agent does not need to reason over all tools, and the state-based examples make the tool's role unmistakable.

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

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

The description gives clear context for when to use this tool: whenever the user needs a next-step recommendation, with state-based guidance for unregistered, unverified, and verified users. It does not explicitly state when not to use it or mention alternatives, but the context is strong enough for an agent to select it appropriately.

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 mutability (readOnlyHint false, destructiveHint true, openWorldHint true, idempotentHint false). The description adds meaningful behavioral detail beyond that: it 'creates escrow, funds the escrow on-chain (USDC), executes the task, and returns the result.' This discloses the financial side effect and the end-to-end execution model without contradicting the annotations.

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

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

The description is two sentences with no wasted words. The action-first sentence front-loads the main behavior, and the second sentence explains the integration context. 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 the tool's complexity (on-chain escrow, funding, agent execution), the description covers the key flow, the intended caller, and the result. The output schema exists, so return details are covered elsewhere. It could add failure/refund behavior, but the core usage context is complete.

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

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

Schema description coverage is 100%, so the schema already explains capability, task_input, and max_price_usdc. The description adds light semantic context by tying capability to the search step and USDC to escrow funding, but it does not materially extend parameter meaning beyond what the schema already provides.

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

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

The description names a specific verb and resource: 'hire an agent from the marketplace to execute a task.' It then enumerates the full pipeline—search, escrow, funding, execution, result—which clearly differentiates it from sibling discovery/contract/verification tools like discover_agents and get_agent_contract.

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

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

The description gives clear context: it is the 'one-call bridge for local orchestrators (Claude Code, Cursor, etc.) to use the marketplace.' It implies this is the end-to-end choice versus multi-step alternatives, but it does not explicitly state when not to use it or name alternative flows.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false, so the safety profile is well covered. The description adds useful context about what content is returned, but it does not disclose additional behavioral traits such as authentication requirements, rate limits, or side effects beyond what annotations already provide.

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

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

The description is a single, information-dense sentence that front-loads the core question ('Where am I in onboarding?') and then lists exactly what is returned. Every segment adds meaningful detail with no filler or redundancy.

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

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

Given the empty input schema, the rich annotations, and the presence of an output schema, the description is complete enough for an agent to select and call the tool correctly. It states the purpose, the return contents, and the immediate value, leaving no critical gaps.

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

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

The tool has zero parameters and schema description coverage is 100%, so the input schema fully documents that no arguments are needed and the owner is derived from the authenticated principal. The description adds no conflicting or confusing parameter information, matching the baseline for a no-parameter tool.

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

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

The description uses a specific verb ('Returns') with a well-defined resource: onboarding status, agents, capability manifests, progress checklist, and testnet config. It clearly identifies the tool's role as a status/read tool and distinguishes it from action-oriented siblings 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?

It clearly implies when to use it: when the user needs to know where they are in onboarding and what they can do next. It does not explicitly name alternatives or state when not to use it, but the onboarding-status framing makes the use case 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?

Beyond the annotations, it discloses the one-time return of secrets, the need to persist them immediately, the in-place session upgrade without reconnect, and the non-idempotent behavior of re-calling (mints a new identity). This is consistent with idempotentHint=false and readOnlyHint=false.

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 key guidance is front-loaded and most sentences carry actionable information. It loses a point because 'no API key/credential needed' and the session-upgrade behavior are essentially stated twice, so there is minor 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 15-parameter, all-optional onboarding tool, the description covers the critical unstated context: one-time secret visibility, persistence requirements, auth requirements, session behavior, next-step dependency, and re-call consequences. The output schema exists, so return-value details do not need to be duplicated.

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% description coverage and every parameter is already documented in detail, so the baseline applies. The tool description adds minimal parameter-level meaning beyond noting that no credentials are required and that a fresh identity is minted.

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: mint an A2AWire identity and return api_key, owner_key, and wallet_private_key. It also positions this tool as the first call when no key is present and warns against re-onboarding, which helps an agent separate it from onboarding-related 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?

Explicitly says to call this first when connected without a key, that no Authorization header is needed on the current session, and that confirm_keys_persisted should be called before money tools. It also states when not to call it again ('do not re-onboard'), giving clear when/when-not 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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral detail by naming the exact fields returned and framing the call as an independent verification, which goes beyond the annotation metadata.

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

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

The description is a single, information-dense sentence with a colon-separated list of returned items. It front-loads the core purpose and contains no filler or redundant elaboration.

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

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

For a no-parameter read-only tool with a declared output schema and strong annotations, the description is complete. It tells the agent exactly what will be returned (address, chain id, RPC, explorer link, USDC token, ABI summary) without needing to duplicate the 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 tool takes zero parameters, and the schema description already covers this fully with 'No arguments'. The description does not need to add parameter details, and it correctly focuses on the output rather than inputs. Baseline for zero-parameter tools is 4.

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

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

The description clearly states the verb 'verify' and the resource 'EscrowVault on-chain', and it lists the concrete returned items. It is unmistakable what the tool does, though it does not explicitly contrast itself with the sibling get_agent_contract, so it stops short of full 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?

There is no guidance about when to use this tool versus alternatives such as get_agent_contract. The word 'verify' implies a verification use case, but no explicit context, prerequisites, or exclusions are provided, leaving the agent to infer the right moment to call it.

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