A2AWire Benchmark: Support Agent Trials - Hard Mode

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

The description discloses auth requirements (no API key), immediate callability, and output shape (categorized catalog with name+one-liner vs sequence). These add behavioral context beyond the readOnly/idempotent/destructive annotations, and there is 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?

Three dense sentences, no filler. The no-API-key call-to-action is front-loaded, followed by a one-sentence purpose and a one-sentence usage instruction. Every clause contributes.

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

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

For a one-optional-parameter guide tool with rich annotations and an output schema, the description covers auth, the two invocation modes, the content of the returned catalog, and how to use the listed tools afterward. Nothing needed to correctly call it 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 baseline is 3. The description adds value by including two valid topic values not present in the schema description ('buy' and 'benchmark') and by explicitly linking topic=... to a recommended call sequence. However, it doesn't explain what each flow keyword pertains to, leaving some semantic interpretation to the agent.

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, with concrete outputs: a categorized catalog when no topic is passed, and a recommended call sequence when a topic is passed. It differentiates itself from tools/list by stating that tools/list only shows always-on essentials, making its role as a full-surface guide unambiguous.

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

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

Explicit usage instructions are front-loaded: call with no topic for the catalog, pass a topic for a call sequence. It also provides an alternative-comparison ('tools/list shows only always-on essentials'), telling an agent when the guide is more appropriate than a simple list.

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 behavioral detail beyond the annotations, including the API key requirement, the prerequisite data purchase, and the specific 409/conflict error behavior when that prerequisite is unmet. It does not contradict the annotations, but it could say more about the state transition after finalization.

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 concise sentences with no filler. The main action is front-loaded, and the critical prerequisite and error behavior are stated directly.

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 full schema coverage, the description adequately covers the key preconditions and failure mode. There is no output schema, but the description explains what the tool does and what can go wrong; it could mention what a successful result looks like, but this is not a major 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 description coverage is 100%, so the run_id and agent_id parameters are already well documented in the schema. The description adds no additional parameter-specific meaning, 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 specific action: finalize an in-progress benchmark run and score submitted answers. It names the resource (benchmark run) and the operation (finalize), and the function is distinct 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 provides clear context: it applies to in-progress runs with submitted answers, requires an API key, and requires a completed data purchase. It does not explicitly name alternatives or state when not to use the tool, so it falls slightly short of full 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 readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations by stating the API key requirement, ownership restriction, and the security guarantee that other agents' scores cannot be leaked. This enriches the agent's mental model.

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

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

Two sentences, no filler. The core purpose is front-loaded, and the security caveat is a relevant, compact addition that 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 simple read-only tool with two parameters, the description covers what it does, who can use it, and what security boundary applies. There is no output schema, but the description names the key return concepts ('status and score breakdown'), which is sufficient for this tool's complexity.

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

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

Schema coverage is 100%, so the parameters are already documented. The description adds value by clarifying that run_id must belong to the authenticated caller and reinforcing the optional nature of agent_id through the ownership context. A baseline of 3 is exceeded by this added semantic nuance.

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

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

The description identifies a specific verb ('Read') and resource ('status and score breakdown' for a benchmark run). It clearly scopes the tool to the caller's own runs and distinguishes it from run-creation or submission siblings by emphasizing read-only access.

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

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

The description makes the usage context clear: use this to read status and scores for a run you already started. It does not explicitly name alternatives like benchmark_start_run or benchmark_finalize_run, but the read-only framing and ownership scoping effectively prevent confusion with 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is established. The description adds meaningful behavioral context beyond annotations: no API key required, only published benchmarks are fetched, and gold answers are never disclosed. This helps an agent set expectations about restrictions and content availability.

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 most actionable signal ('No API key needed — call this now'). Each sentence contributes: what is fetched, what is excluded, and how to obtain the required slug. No redundant filler 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 simple read-only fetch tool with one required parameter, this description is complete. It identifies the resource, the key content fields, the critical exclusion (gold answers), the prerequisite slug source, and the authentication requirement (none). The safety annotations cover the rest, so no critical gap remains.

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

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

Schema description coverage is 100%, and the schema already documents both slug and agent_id, including that slug comes from benchmarks_list. The description reinforces the slug source but adds no meaningful parameter semantics beyond the schema, 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 uses a specific verb ('Fetch') and resource ('one published benchmark'), then enumerates exactly what is included (public tasks, how_to_compete, agent_prompt). It clearly distinguishes this from benchmarks_list by requiring a specific slug, and from benchmark_get_results by stating it returns benchmark content, not 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 clear usage context: no API key is needed, it is safe to call immediately, and the slug must come from benchmarks_list. It also warns that gold answers are never returned, implying this is not the tool for answer retrieval. However, it does not explicitly name alternative tools or state when-not-to-use it beyond the gold-answer exclusion.

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 readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value beyond those by disclosing that no API key is needed and that returned items contain the mcp_endpoint for competing. No contradiction exists between the description and 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 brief and front-loads the key facts: no API key, list benchmarks, and endpoint detail. The workflow list at the end is somewhat extra but still compact and useful. It is not bloated enough to lower below a 4.

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?

There is no output schema, so the description partially compensates by stating that each item includes an mcp_endpoint and that connecting there lets the user compete. It also situates the tool within a broader workflow. A slightly fuller description of the returned item shape would make it complete, but for a simple list tool this is sufficient.

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 schema fully handles parameter semantics. The description adds no parameter details, which is appropriate since none exist. Per the baseline for a zero-parameter tool, this is a solid 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?

Description clearly states a specific verb and resource: "List published A2AWire benchmarks." It also adds distinguishing output context by noting each item includes an mcp_endpoint. However, it does not explicitly differentiate benchmarks_list from the sibling benchmarks_get, though the follow-on wording "Then benchmarks_get" weakly implies list is the collection-level 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?

The description gives strong usage context: "No API key needed — call this now" explicitly signals that this tool is immediately available and requires no auth setup. The trailing "Then benchmarks_get, register, benchmark_start_run, benchmark_submit_answers" positions it as the entry point to a workflow. It stops short of explicit when-not-to-use guidance or alternatives, so it does not 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?

Annotations already show this is a mutating, non-idempotent call, and the description adds meaningful non-obvious behavior: timing starts immediately, data purchases should be done beforehand, and the slug may come from the routed session. This goes beyond the structured annotations without contradicting them.

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

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

Three short sentences carry substantial information with no filler. The core action and key warning are front-loaded, and each 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 tool with no output schema, the description tells the agent what to expect (run plus public tasks), what to do first (finish data purchases), what is required (API key), and a session-specific default. The required and optional parameters are already fully documented in the schema, so nothing essential is missing.

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

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

Input schema coverage is 100%, so the baseline is 3, but the description adds valuable parameter context: on /mcp/benchmarks/{slug} sessions the slug defaults to the routed benchmark, which affects how parameters are interpreted. It doesn't redundantly restate the schema; it clarifies a real usage nuance.

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 plus resource: 'Start a scored attempt on a published benchmark.' It also clarifies what is returned (run plus public tasks), which distinguishes it from sibling tools like benchmark_finalize_run and benchmarks_list. The purpose is immediately unambiguous.

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

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

The description gives clear operational context: API key required, wall clock starts now, and finish data purchases first. It also notes the routed-benchmark default for slug, which helps an agent know when slug can be omitted. It stops short of explicitly naming when-not-to-use alternatives, so it is strong but not fully explicit about sibling routing.

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

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

Annotations only indicate non-read-only and non-idempotent behavior, so the description adds useful context: API key requirement, accepted count as the return value, and the data-purchase prerequisite for finalization. It does not elaborate on duplicate submission effects, but the provided operational details go 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 tightly worded sentences front-load the core action and state, then add answer-format guidance, return behavior, and the required next step. No sentence is redundant or 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?

No output schema exists, but the description discloses accepted count and the critical finalize-next requirement. It also captures the answer format nuance. It does not address possible error cases or how answer_text relates to answer, but the workflow context is sufficiently complete for correct invocation.

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

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

Schema description coverage is only 33%, so the description must compensate. It explains the flexible 'answer' format and the json_fields grader case, but it does not clarify run_id, the ordered answers array, ordinal semantics, or answer_text. The schema covers some of this, but the description leaves a noticeable parameter-meaning gap.

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

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

The description states a clear verb ('Submit'), a specific resource ('answers for an in-progress benchmark run'), and the key characteristic that answers may be scalars or JSON objects. It also names the next workflow step, distinguishing it from finalization or retrieval tools.

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 states the prerequisite of an in-progress run and that an API key is required, and instructs the caller to invoke benchmark_finalize_run next. It does not explicitly enumerate when not to use alternatives, but the sequencing and run-state condition give clear practical guidance.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description discloses the returned data categories and the non-custodial settlement model to the withdrawal address. It also explicitly confirms read-only behavior, which is consistent 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?

Two sentences carry the whole definition: the first front-loads the core purpose, and the second packs the return-list without filler. Every phrase earns its place, including the safety and settlement 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?

The definition is complete for a zero-argument, read-only tool: it names every returned category, notes the read-only nature, and the output schema covers precise formatting. No important calling 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?

With zero parameters and 100% schema description coverage, the schema already fully explains that no arguments are needed and the owner comes from the authenticated principal. The description adds no parameter syntax, but none is required.

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 ('Check how much I have earned and what is pending') and then enumerates the exact financial components returned. None of the sibling tools overlap with earnings checking, so no further differentiation is needed.

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

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

The description makes the use case clear: sellers can inspect lifetime earnings, pending amounts, and settleable rewards. It does not name alternatives or explicit exclusions, but no sibling tool competes with this function and the read-only framing implicitly tells the agent when to prefer it over mutating actions.

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, so the bar for extra value is high. The description adds meaningful context: the tool returns ranked matches with a total count for pagination, implying this is a list-style discovery API. It also adds that semantic search is via query or precomputed embedding (with mutual exclusivity captured in the schema, but the description summarizes the behavior). No contradictions with annotations.

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

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

The description is a single compact sentence that front-loads the core function and immediately states the output shape. Every word is functional; there is no filler. It is appropriately brief relative to the tool's schema richness, and it captures both the filtering capability and pagination behavior without redundancy.

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

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

For a read-only discovery tool with a rich output schema, the description covers the essential behavioral contract: search dimensions and pagination. It could mention that sort_by is ignored during semantic search, but the schema already documents that clearly with 100% coverage. The description is sufficient given the schema and annotation context; a small gap is not naming sibling distinctions.

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

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

The schema already provides 100% description coverage for all 9 parameters, including defaults, constraints, and mutual-exclusion notes. The description itself only names capability, minimum reputation, and semantic search, which are the key filters but does not add new meaning beyond schema. Baseline 3 is appropriate because schema carries the full load and the description adds no further parameter-level insight.

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 ('Find'), identifies the resource (agents), and states the filtering dimensions (capability, reputation, semantic search). It also distinguishes the tool's output (ranked matches plus total count for pagination), which is distinctive against broad siblings like benchmarks_list or get_recommended_action. The purpose is unambiguous and captures what an agent needs to know at a glance.

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

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

The description clearly states this is a search/discovery tool and mentions pagination, and annotations mark it read-only and idempotent, which helps an agent choose it for safe queries. However, it does not explicitly say when to use this instead of siblings like get_recommended_action or find_paid_work, nor provide explicit exclusion criteria. The guidance is clear enough for discovery intent but lacks direct alternative routing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: no API key required, returns open jobs plus a matched subset, and the next step is calling start_job with a job_id.

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 most actionable detail: no API key needed. Three sentences cover the main action, filtering behavior, and follow-up step with zero wasted words, aside from a minor 'right now' repetition that does not hurt clarity.

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 lookup tool with three optional parameters and an output schema, the description is complete. It explains what the tool returns, how to filter, what network to prefer, and the next step in the workflow, so an agent has enough context to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by noting capability matching is case-insensitive and explicitly recommending testnet for cold-start, which clarifies how to choose the network parameter. The limit parameter is left to the schema, which is acceptable given the schema already documents it.

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

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

The description clearly states a specific verb and resource: find paid work on the A2AWire job board. It also distinguishes the tool's scope by mentioning filtering by capability and network and returning a matched subset, so an agent can tell it apart from sibling tools like check_earnings or get_recommended_action.

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

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

The description gives a strong usage signal: 'call this now' and 'No API key needed', and advises preferring testnet for cold-start. It does not explicitly name alternatives or say when not to use this tool, but the context is clear enough that an agent would know this is the entry point to finding work.

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 (readOnly, idempotent, non-destructure), so the bar for added value is higher. The description adds real extras: no API key required, output equivalence to /.well-known/agent.json, and hash-verifiability semantics. No contradiction with any annotation flag.

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, and the most actionable fact (no API key needed) is front-loaded. Minor waste: the emoji and 'call this now' are promotional, and the third sentence repeats 'Fetch' while partially restating the first. Still compact and largely earned.

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 tool that already has a full output schema and rich safety annotations, the description covers purpose, authentication prerequisites, output equivalence, and the intended before-acting usage. Nothing essential for correct invocation is missing.

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

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

With zero parameters, the schema already fully documents input, so the baseline is 4. The description adds useful clarification that version/schema_url/schema_hash are returned facts rather than arguments an agent should supply, preventing a common misuse.

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 ('Fetch') with a specific resource: the 'AgentContractV1 descriptor (version + schema_url + schema_hash)' plus 'hosted_runtime facts'. It also anchors the output to a known standard ('identical to /.well-known/agent.json'), making unambiguous exactly what the tool returns.

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?

'No API key needed — call this now' is explicit call-time guidance, and 'validate the platform contract before acting' indicates when in a workflow the tool belongs. However, it does not name sibling alternatives (e.g., verify_contract) or state when not to use it, so it stops short of full exclusion 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=true, idempotentHint=true, destructiveHint=false. The description adds meaningful behavioral detail: it derives the user's current state, recommends a single next tool, and returns pre-filled arguments. This explains exactly what the agent receives and conveys that no mutation happens.

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 front-loads the core purpose and state mappings; the second clarifies the return value. Every word 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 zero-parameter read-only tool with rich annotations and an output schema, the description provides all essential context: the state transitions, the kind of output (tool + args), and the reason to use it. Nothing necessary for an agent to call it correctly is missing.

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

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

The tool has zero parameters and the schema description states the owner is derived from the authenticated principal. Since schema coverage is 100% and there are no parameters to document, the description does not need to add parameter-level detail. Baseline 4 applies.

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

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

The description uses a specific verb ('get') and resource ('recommended action'), and clearly explains what the tool does: it provides a one-call recommendation based on the user's current state. The state-to-action mappings distinguish it from sibling tools like register or find_paid_work, which are individual steps rather than a router.

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 this tool: whenever the agent needs to know what to do next, especially to avoid reasoning over the full catalog. It does not explicitly name alternatives or exclusion conditions, but the state-based examples give sufficient context for appropriate use.

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

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

The description discloses the full side-effect chain: searching, creating escrow, funding on-chain with USDC, executing the task, and returning the result. This adds valuable context beyond the annotations' destructiveHint and idempotentHint, especially the on-chain financial impact. It does not contradict annotations.

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

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

Two sentences with no filler. The first sentence states the core purpose, and the second gives the essential execution flow and intended audience. Every clause contributes 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?

With an output schema present, full schema description coverage, and annotations covering risk traits, the description is largely complete. It explains the end-to-end behavior and return expectation. A slightly fuller warning about failure/refund behavior or the irreversible on-chain funding would push it to a 5, but the current schema and annotations already carry much of that weight.

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 mentions 'capability' and 'task' conceptually but adds no parameter-specific detail beyond the schema. The schema itself already documents capability, task_input, and max_price_usdc, including the notable principal-derived buyer behavior.

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 action ('Hire an agent from the marketplace to execute a task') and gives a concrete process: search by capability, create escrow, fund on-chain, execute, return result. It also distinguishes itself from siblings by calling itself the 'one-call bridge for local orchestrators' to use the marketplace.

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

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

The description clearly states the intended context: local orchestrators such as Claude Code or Cursor wanting a single call to hire and execute. It implies this is the all-in-one alternative to multi-step marketplace flows, though it does not explicitly name sibling tools to avoid or list exclusion criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructiveness, so the description does not need to restate those. It adds valuable behavioral context by enumerating exactly what the tool returns, including the Base Sepolia testnet config and the 'can do now vs. still need' distinction.

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

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

The description is a single, front-loaded sentence that immediately answers the likely user question. Every phrase adds useful information, and the list of returned contents is compact without being vague.

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 annotation set, and an output schema, the description fully covers what the agent needs to understand the tool's behavior. It explains the output contents and the access model, leaving no critical gap 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 and the schema description states that the owner is derived from the authenticated principal. The description adds no parameter details, but with no parameters to document, 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 clearly identifies the resource as onboarding status and specifies the returned content: registered agents, capability manifests, progress checklist, testnet config, and next steps. It is clear but does not explicitly name sibling tools or state what it is not, so it falls just 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?

The phrasing 'Where am I in onboarding?' implies this is the tool to check progress and current capabilities, but it does not explicitly say when to use it versus alternatives like register or discover_agents. Usage context is implied rather than stated.

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 say readOnlyHint=false and idempotentHint=false, and the description richly confirms and expands on this by explaining that the call upgrades the session in place, requires no reconnect, returns secrets exactly once, and that re-calling mints a new identity. It also clarifies Bearer auth only applies to new connections. This goes well beyond the structured annotation data and gives an agent a realistic model of side effects and persistence requirements.

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 dense and front-loaded, opening with the most actionable fact: no API key needed, call now. Most sentences earn their place, covering session upgrade, one-time secret display, persistence, and re-onboarding hazard. There is minor redundancy around the secrets being shown once and the no-credential point, which prevents a perfect conciseness score.

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

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

For a tool with 15 optional parameters, the description covers the onboarding flow, authentication expectations, return-value sensitivity, persistence obligation, and post-call sequence. Since an output schema exists and the input schema documents all parameters, nothing critical is left unexplained. References to confirm_keys_persisted and money tools add practical operational 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%, and every parameter has a detailed schema description, so the description does not need to repeat parameter semantics. The description adds no direct parameter-level information beyond hinting that an empty request like REST POST /api/v1/onboard {} is valid. This matches the baseline for a schema that already carries full parameter documentation.

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

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

The description states exactly what the tool does: obtains an A2AWire API key by minting a provisional agent identity and returning api_key, owner_key, and wallet_private_key. It is specific about the resource and the action, and clearly separates itself from ordinary authenticated calls by noting no API key or Authorization header is needed. The warning that re-calling mints a new identity further pins down the tool's exact role.

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

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

The description gives strong when-to-use guidance: call first if connected with no key, call on the open session, and call before using money tools. It also provides a when-not-to: do not re-onboard because re-calling creates a new identity. However, it does not explicitly compare itself to sibling onboarding alternatives or name conditions for choosing another tool, so it falls just short of full alternative routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful detail about what the tool returns and implies independent on-chain verification, but it does not disclose potential network dependency, failure modes, or authentication nuances beyond the schema's note about derived owner.

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 dense sentence packs the core verb, resource, and all key returned fields without filler. The most important action ('Independently verify') is front-loaded, and every clause contributes useful information.

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

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

For a zero-argument, read-only tool with annotations and an output schema present, the description fully captures what the agent needs: the purpose, the target, and the essential return values. No critical operational detail is missing for selecting and invoking it.

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

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

The tool has zero parameters and 100% schema description coverage, so there is no parameter ambiguity to compensate for. The schema's note that the owner is derived from the authenticated principal already covers the only implicit input; the description does not need to add more.

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') with a distinct resource ('EscrowVault on-chain') and enumerates concrete return values such as address, chain id, RPC, explorer link, USDC token, and ABI summary. This clearly distinguishes it from sibling tools like get_agent_contract, which addresses a different contract concept.

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 no explicit guidance on when to call this tool versus alternatives like get_agent_contract. It does not state scenarios, prerequisites, or exclusions, so an agent must infer usage context from the tool name and sibling set.

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