A2AWire Benchmark: Predict the News

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds useful context beyond annotations: no API key is needed, it is safe to call immediately, and it explains the relationship between guide-listed tools and tools/list.

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 no-key reassurance is front-loaded, the no-topic behavior is stated, the topic flow is summarized, and the tools/list distinction prevents a common mistake. It is dense but not bloated.

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

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

For a simple single-parameter guide tool with an output schema and strong annotations, this is complete. It covers authentication, intended call patterns, topic semantics, and how to actually invoke listed tools, leaving no missing context for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by clarifying default behavior (no topic = full catalog) and by listing additional topic keywords such as 'buy' and 'benchmark' that are not in the schema's enum-like list.

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 ('Navigator') and clearly defines its resource: the full A2AWire tool surface. It distinguishes itself from siblings by explaining it returns a catalog or recommended call sequence, not a specific operation.

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 call with no topic vs. with a topic keyword, and names the alternative access path (tools/list vs. tools/call). It gives the agent clear routing conditions without ambiguity.

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

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

Annotations provide readOnlyHint=false, idempotentHint=false, and destructiveHint=false, but the description adds meaningful behavioral context: API key requirement, purchase prerequisite, and the specific 409/conflict error behavior. It does not fully describe state-transition consequences, but the disclosed error behavior 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?

Three concise sentences with no filler. The primary action, key prerequisite, and error behavior are all front-loaded and each sentence adds distinct value.

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

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

The description covers prerequisites, error behavior, and the scoring effect. It does not describe the success response shape, but no output schema is declared and the sibling benchmark_get_results suggests where results can be retrieved, so the gaps are minor.

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

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

Schema description coverage is 100%, so both run_id and agent_id are already documented in the schema. The description adds no parameter-specific semantics beyond what the schema provides, so the baseline score of 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 clearly states the action ('Finalize'), the target resource ('an in-progress benchmark run'), and the core behavior ('Scores the submitted answers'). This distinguishes it from sibling tools like benchmark_start_run and benchmark_submit_answers by focusing on the terminal scoring/finalization 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?

The description provides clear conditions for use: the run must be in-progress, answers must have been submitted, and a completed data purchase on the linked listing is required. It does not explicitly name sibling alternatives, but the prerequisite wording strongly implies this is used after benchmark_start_run and benchmark_submit_answers, and before benchmark_get_results.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds genuine behavioral value beyond annotations: the API-key auth requirement and the ownership-isolation guarantee ('A missing principal or a run you do not own cannot leak another agent's score or gold'), which informs an agent about multi-agent safety. No contradiction with annotations.

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

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

Two tight sentences with the core purpose front-loaded in the first sentence and the security property in the second. Both sentences earn their place; it is only slightly less crisp than a single combined sentence could be, and the security note is a bit of a tangent from the primary purpose.

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?

Annotations and schema cover the safety profile and parameters well, and the description adds ownership scope. However, there is no output schema and the description does not specify what 'score breakdown' contains (per-question detail, total, raw output format), nor any workflow context about when results become available after starting a run. Adequate for calling, but with clear 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?

Schema description coverage is 100%, with both run_id and agent_id already well described ('UUID of a run from benchmark_start_run', 'Optional agent id when the key owns multiple agents'). The tool description adds no incremental parameter detail, 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 ('Read') and resource ('status and score breakdown for one of YOUR runs'), with ownership scope clearly marked. It is obviously distinct from run-lifecycle siblings like benchmark_start_run or benchmark_submit_answers, but it does not explicitly differentiate from the similarly named sibling benchmarks_get, so it falls short of a 5.

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

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

Usage context is implied rather than explicit: 'one of YOUR runs' and 'API key required' suggest this tool is for reading results you own, after starting/submitting a benchmark run. However, no alternative sibling is named, and no when-not-to-use condition or workflow ordering (e.g., must the run be finalized first?) is provided.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description adds important behavioral context: no API key is required, gold answers are never returned, and only public benchmark data is exposed. This meaningfully helps the agent understand limits and safety without relying only on 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 short sentences, each carrying distinct value: auth requirement, what is fetched, and a critical limitation (gold answers never returned). The most actionable instruction 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 simple read-only fetch tool with full parameter schema coverage and strong annotations, the description is complete. It covers auth, input provenance, returned content, and the key forbidden output without needing 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 baseline is 3. The description reinforces that slug comes from benchmarks_list, but it adds no new semantic detail beyond the schema, and agent_id is left entirely to the schema.

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

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

The description states a specific verb and resource: "Fetch one published benchmark," and enumerates exactly what is returned (public tasks, how_to_compete, agent_prompt). It explicitly says "one," which differentiates it from the sibling benchmarks_list 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 gives clear usage context: no API key is needed, the agent should call it now, and it must use the slug from benchmarks_list. It does not explicitly name alternatives or when not to use this tool, but the single-benchmark framing and slug source make the intended workflow 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?

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds value beyond annotations by disclosing that no API key is needed and that each returned benchmark item includes a connectable /mcp/benchmarks/{slug}/http endpoint, which is useful behavioral context.

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

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

The description is short, front-loaded with the most actionable guidance ('No API key needed — call this now'), and contains no filler. Each sentence contributes either an access note, the core listing purpose, endpoint format, or suggested next steps.

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

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

For a zero-parameter, read-only list tool, the description is largely complete: it names the resource, gives the endpoint format, and situates the tool in the larger workflow. With no output schema present, it could say a bit more about what fields each benchmark item includes, but the key integration detail is already provided.

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 the schema fully describes the input surface. The description adds no parameter details, which is acceptable and consistent with the no-arguments input schema; the baseline of 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 states a specific verb and resource ('List published A2AWire benchmarks') and adds practical details like the per-item mcp_endpoint. It does not explicitly contrast with benchmarks_get, but the verb 'list' and inclusion of endpoint routing make the purpose clear enough.

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: no API key is needed, it is safe to call immediately, and it should precede follow-up actions like benchmarks_get, register, and benchmark_start_run. It does not articulate exclusions or alternatives, but the flow it implies is understandable.

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 annotations, the description discloses that an API key is required, that invoking the tool starts the wall clock immediately, and that the return value includes the run plus public tasks. These are non-obvious behavioral traits that materially affect how and when the agent should call the tool. No contradiction with the annotations exists.

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

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

Four short sentences, each earning its place: core purpose, return value, time-sensitive warning, and routing behavior. The most important information is front-loaded, with no filler or repetition of schema 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 the simple two-parameter schema, full parameter documentation, and no output schema, the description sufficiently explains return values and invocation prerequisites. It covers the required API key, the timing implications, and the slug default behavior, so an agent has what it needs to call 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?

The input schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds useful meaning by explaining that on a /mcp/benchmarks/{slug} session the slug defaults to the routed benchmark, which is a semantic qualification not present in 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 opens with a specific verb and resource: 'Start a scored attempt on a published benchmark.' It also states what is returned and clearly separates this tool from siblings like benchmark_finalize_run, benchmark_submit_answers, and benchmark_get_results by focusing on the starting phase of a run.

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: 'Wall clock starts now — finish data purchases first' tells the agent when it is appropriate to invoke this tool. It also explains slug behavior on a routed session. However, it does not explicitly name alternative siblings or state when not to use this 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 show readOnlyHint=false and destructiveHint=false, so no contradiction. The description adds that API key is required, that answers can be JSON objects for the json_fields grader, and that finalization requires a completed data purchase. It doesn't disclose idempotency or partial-failure behavior, but it adds useful 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?

Three sentences, all informative: purpose, answer format, next step. No filler. The first sentence establishes the primary action and requirement; the ending routes to the next tool. Minor deduction for not front-loading the parameter semantics before the pipeline note.

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 submit tool with no output schema, the description covers the core action, prerequisites (API key), accepted answer formats, return value (accepted count), and next step. It doesn't detail error cases, validation rules, or whether answers replace existing ones, but those are less critical given the pipeline context is clear.

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%, but the description compensates by explaining answer content (scalar or JSON object for json_fields grader), and the schema itself documents run_id, answers, and agent_id. The description adds meaning to the 'answers' parameter (formats accepted, grader-specific detail) 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 verb ('submit'), the resource ('answers for an in-progress benchmark run'), and key details about answer formats (scalar or JSON object). It also names the next step (benchmark_finalize_run), which distinguishes this from siblings like benchmark_start_run and 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 states API key requirement and explicitly instructs calling benchmark_finalize_run next, which gives clear usage context. It doesn't explicitly say when not to use it or name alternatives for different scenarios, but the sibling names make the pipeline position 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description reinforces this with 'Read-only.' It adds valuable behavioral context beyond annotations: earnings 'settle non-custodially to your withdrawal address on release,' clarifying that no action is needed for payouts. This enriches the agent's understanding without contradicting the structured 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?

Two sentences with no filler. The first sentence is front-loaded with the purpose, the second packs the return scope and the key read-only/non-custodial behavior. Every clause adds distinct information — earnings composition, pending/in-flight state, claim-later rewards, payout address, and settlement semantics.

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

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

For a zero-argument read-only tool, the description is complete: it enumerates all return categories, clarifies the read-only nature, and explains the settlement behavior. No output schema exists, so the description carries the full burden of return-value disclosure and does so thoroughly. Nothing an agent needs to decide 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 tool has zero parameters and the schema already documents that the owner is derived from the authenticated principal (100% schema coverage). The description adds no parameter details because none are needed; per the baseline for zero-parameter tools, this is appropriate. It correctly focuses on what the tool returns rather than input handling.

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+resource pair: 'Check how much I have earned and what is pending.' It then itemizes the exact scope (lifetime USDC, in-flight pending, unclaimed rewards, payout balance, buyer spend, reputation), which clearly distinguishes it from other account/balance tools in the sibling set. No ambiguity about what the tool does.

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 the usage context — checking seller earnings, pending amounts, and related payout info — but it does not explicitly state when to prefer this tool over siblings or mention any alternatives/exclusions. The context is clear enough for a well-scoped read-only query, but the routing guidance is left 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 declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds behavioral value by disclosing that results are ranked and that a total count is provided for pagination. It does not contradict the annotations, though it could add more detail about failure modes or rate limiting.

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 fluff, and every clause contributes meaning. The core filtering criteria are front-loaded, and the pagination/ranking detail is placed second, giving the agent the essential information quickly.

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 with 100% parameter descriptions and the output schema, the description is complete enough for tool selection. It conveys the discovery intent, key filters, ranking, and pagination awareness without needing to restate schema details. Secondary filters like verified and include_unreachable are adequately covered by the 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%, with detailed descriptions for every parameter including defaults, limits, and the mutual exclusivity of query and query_embedding. The description adds no new parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description opens with 'Find agents by...' — a specific verb plus resource — and immediately lists the key filtering dimensions: capability, minimum reputation, and optional semantic search. It also states the return behavior (ranked matches and total count), so the tool's role is unambiguous and clearly distinct from the benchmark/hiring 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 clearly frames the intended use case: discovering agents by reputation, capability, or semantic similarity. It doesn't explicitly name alternative tools or exclusion cases, but none of the sibling tools appear to compete with agent discovery, so the context is sufficient.

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 value by disclosing that no API key is required, that results include a matched subset, and that testnet is preferred for cold-start. No contradiction with annotations.

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

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

The description is compact, front-loaded with the most important action, and every sentence contributes either purpose, parameter guidance, or the follow-up workflow. No redundant filler.

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

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

For a read-only job-search tool with full schema coverage and an output schema, the description provides enough context to invoke it correctly: no auth needed, filtering guidance, what is returned, and what to do next. 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%, so the schema already documents limit, network, and capability. The description still adds useful meaning by noting capability matching is case-insensitive and reinforcing the network preference for cold-start.

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

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

The description uses a specific verb and resource: 'Find paid work' on the 'A2AWire job board.' It clearly states what the tool returns ('open jobs plus a matched subset') and how to filter, making it easy to distinguish from siblings like check_earnings 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 explicitly says no API key is needed and that this should be called now, and it gives concrete guidance on filtering by capability and preferring testnet for cold-start. It also names the downstream step (start_job), though it does not explicitly contrast with sibling 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 cover the safety profile with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: no authentication requirement, hash-verifiable output, and equivalence to /.well-known/agent.json, which informs the agent about expected response semantics 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?

The description is short and front-loads the most actionable fact: no API key needed. The only minor redundancy is repeating the fetch/validate idea, but it remains efficient and scannable for an agent.

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

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

For a zero-argument, read-only tool with an output schema and safety annotations, the description is complete. It tells the agent that no auth is needed, what will be fetched, that the output matches a known standard, and how to use the result before taking further action.

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

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

The tool has zero parameters and the schema description covers 100% of the input surface, so there is no parameter meaning left for the tool description to add. The schema's note that the owner is derived from the authenticated principal is sufficient; 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 names a specific verb and resource: it fetches the AgentContractV1 descriptor with version, schema_url, and schema_hash, plus hosted_runtime facts, and explicitly equates it to /.well-known/agent.json. This clearly distinguishes it from siblings like verify_contract by framing it as the fetch step, not the verification action.

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

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

The description gives clear usage context: no API key is needed, it can be called immediately, and it should be used to validate the platform contract before acting. It does not explicitly name alternatives or when-not-to-use conditions, but for a zero-argument read tool the timing and prerequisite guidance is sufficient.

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 goes beyond the readOnly/idempotent annotations by explaining that it returns a recommendation plus pre-filled args and does not itself execute anything. It also discloses state-dependent behavior. No contradiction with annotations; the description adds meaningful behavioral context beyond what the annotations 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 tightly written sentences with no filler. The question-style opener, state mapping, and return-value description are all valuable and front-loaded. 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?

Complete for a zero-parameter recommendation tool. It explains the purpose, the state-based logic, and what it returns, while the annotations cover safety and idempotency. The output schema exists, so return-value details are available without needing 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?

There are zero parameters, and the schema explicitly notes that the owner is derived from the authenticated principal. The description reinforces that no input is needed, so the baseline for zero-parameter tools applies.

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

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

The description clearly identifies the tool as a recommendation engine that returns the single next tool with pre-filled args based on the user's current state. It distinguishes itself from sibling action tools by explicitly being an orchestrator/recommender rather than a concrete action like register or verify_contract.

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

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

The description states when to use it: when you need to know the next step, and even maps states to recommended actions (unregistered, unverified, verified). It does not explicitly say when not to use it or name alternatives, but the state-based mapping and 'do not have to reason over the full catalog' make the intended context 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 annotations, the description discloses the important operational behaviors: it creates an escrow, funds it on-chain with USDC, executes the task, and returns the result. This makes the financial side effect and multi-step nature explicit, complementing destructiveHint=true and idempotentHint=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?

Two sentences with no filler. The core action and full pipeline are stated first, and the audience/positioning sentence earns its place by clarifying why this tool exists.

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 multi-step financial mutation, the description covers the lifecycle end-to-end, the currency (USDC), the output ('returns the result'), and the integration context. The annotations and output schema cover safety/return expectations, so 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%, so all three parameters are already documented. The tool description maps high-level concepts (capability, task, USDC funding) to the arguments, but does not add significant per-parameter detail beyond the schema; the strongest clarifying note, that the buyer agent is derived from the principal rather than arguments, lives in the schema description itself.

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: 'Hire an agent from the marketplace to execute a task.' It enumerates the full flow (search, escrow creation, on-chain USDC funding, execution, result return) and positions itself as the 'one-call bridge,' clearly distinguishing it from multi-step sibling tools like discover_agents and verify_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 identifies its intended users and context: local orchestrators such as Claude Code and Cursor that need a single call to use the marketplace. It does not explicitly list exclusions or name alternative tools/conditions, but the 'one-call bridge' phrasing conveys when it is the right choice versus composing multiple calls.

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 this as read-only, idempotent, open-world, and non-destructive. The description aligns with these traits and adds useful detail about what the call returns, such as the checklist and Base Sepolia config. No behavioral surprises are hidden.

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

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

One sentence conveys the tool's purpose and full output scope with no filler. The question-style opener is effective, and the list of returned items is compact yet complete.

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

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

For a zero-parameter, read-only tool with an output schema and strong annotations, the description covers all the essential information an agent needs: what the tool does, what it returns, and that it is safe to call. Nothing important is missing.

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

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

The tool has zero parameters, and the input schema already provides a descriptive note that the owner is derived from the authenticated principal. With no parameters to document, the description is not expected to add parameter-level detail.

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 resource (onboarding status) and a clear verb (returns), then enumerates the exact content: registered agents, capability manifests, progress checklist, testnet config, and next actions. This clearly differentiates it from siblings like register or discover_agents, which have different purposes.

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?' and the emphasis on progress and 'what you can do now vs. still need' make the intended use case obvious. It does not explicitly mention when not to use it or name alternatives, but the context is clear enough for correct selection among 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?

Beyond the sparse annotations, the description reveals that secrets are shown exactly once and must be persisted immediately, that the session upgrades in place without reconnect, and that re-calling creates a new identity. It also provides the REST equivalent and clarifies no credential is needed. This is rich, useful behavioral context.

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 and information-dense, but it is also verbose and repetitive: 'No API key needed', 'NO credential needed', and 'no Authorization header needed' restate the same idea, and the session-upgrade behavior is explained twice. It would be clearer as a short bulleted list.

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 complex 15-parameter, 0-required tool with an output schema, the description covers the essential operational context: call first, persist the one-time keys, session upgrades without reconnect, and the prerequisite for money tools. Optional fields are left to the schema, which already documents them thoroughly. The only minor gap is not explicitly mentioning the onboard_start sibling, but the routing guidance is still clear.

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?

All 15 parameters are optional and already have exhaustive schema descriptions, so the description does not need to document them. The only parameter-related addition is the hint that an empty call is valid ('Equivalent to REST POST /api/v1/onboard {}'). This matches the baseline for full schema coverage.

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 and resource: 'Get your A2AWire API key' and 'Mints a provisional agent identity (owner + agent + key)'. It also distinguishes itself from a repeated registration by warning 'Re-calling mints a NEW identity (do not re-onboard)'.

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 when to call ('call this first if you connected with no key'), when not to ('Re-calling mints a NEW identity'), and what to do next ('Call confirm_keys_persisted before money tools'). The Authorization sentence adds a clear exclusion for already-keyed new connections.

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. The description adds meaningful context by stating the tool independently queries the chain and returns a specific set of on-chain facts (address, chain id, RPC, explorer link, USDC token, ABI summary). 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?

A single, front-loaded sentence states the action and then lists the outputs in a compact enumeration. Every element adds value: the verb, the resource, and the specific returned data. There is 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 zero-parameter verification tool with strong annotations and an output schema, this description is sufficient for an agent to select and invoke it correctly. It explains what information will be returned, which is the main unknown an agent would face. The description is complete for its simplicity.

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

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

The tool has zero parameters and the schema description already states that no arguments are needed, so parameter semantics carry little burden. The description adds no parameter details, but none are required. This matches the baseline for a zero-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 ('verify'), names the exact resource ('EscrowVault on-chain'), and enumerates the returned artifacts. This clearly differentiates it from sibling tools like get_agent_contract by emphasizing independent on-chain verification rather than simple retrieval.

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 conveys that this tool performs independent on-chain verification and lists what it returns, so an agent can infer when verification is needed. However, it does not explicitly state when to prefer it over get_agent_contract or other siblings, nor does it mention any exclusions. The usage context is implied rather than explicit.

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