Support Action Gate

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond that: no API key required, every listed tool is callable via tools/call by name, and tools/list only shows essentials. This is genuinely additive and does not contradict the annotations.

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

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

The description is compact and front-loaded with the most operationally important signal: no API key needed. Each sentence carries distinct information, though the emoji and 'call this now' are minor fillers that add little. Overall, it is efficient without being minimal.

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

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

For a one-parameter, read-only guide tool with an output schema and rich annotations, the description is nearly complete: it explains what the tool returns, when to omit or pass topic, and how the results connect to tool invocation. The only material gap is the inconsistent topic list between the description and the schema, which could slightly confuse an agent relying on both.

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% for the single optional topic parameter, so the baseline is 3. The description enriches the parameter by explaining the difference between omitting it and passing a topic, but the topic list in the description (including buy and benchmark) is not fully mirrored in the schema's example list, creating minor ambiguity. Since there are no enums, this is not a hard conflict.

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 a specific verb and resource: it is a navigator/catalog for the full A2AWire tool surface. It also distinguishes itself from tools/list by noting that the guide lists every callable tool while tools/list shows only always-on essentials. This separates it cleanly from the operational sibling 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?

The description gives explicit when-to-use instructions: call with no topic for the full catalog, or pass a topic for a recommended call sequence. It also references the tools/list alternative and explains the difference, so an agent can decide correctly without extra inference.

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

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

Beyond the annotations, the description discloses that an API key is required, that a completed data purchase is a prerequisite, and that failure returns a 409/conflict payload. This is useful behavioral context that annotations alone do not provide, though it does not describe behavior for already-finalized runs.

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 primary action is front-loaded, followed by prerequisites and error behavior, making it easy for an agent to parse 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?

For a tool with a single required parameter and no output schema, the description covers purpose, auth requirement, prerequisite, and failure mode. Minor gaps include the exact success response payload and behavior when the run is not in-progress, but the description is still largely 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?

Schema description coverage is 100%, so the input schema already documents run_id and agent_id well. The tool description adds no 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 uses a specific verb ('Finalize') and resource ('in-progress benchmark run') and adds the outcome ('Scores the submitted answers'). It is clearly distinct from siblings like benchmark_start_run and benchmark_submit_answers, though it does not explicitly name an alternative 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 context: finalization happens for an in-progress benchmark run, requires an API key, and requires a completed data purchase. It implies use after starting and submitting answers, but it does not explicitly state when not to use it or name 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context beyond annotations: the API key requirement and a confidentiality guarantee that missing principals or non-owned runs cannot leak another agent's score or gold. This strengthens trust and clarifies access behavior.

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

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

Two dense, purposeful sentences. The first fronts the verb, resource, and auth requirement; the second adds a high-value security guarantee. There is no filler or redundancy.

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

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

Given a simple 2-parameter read tool with comprehensive annotations, the description covers purpose, auth, ownership scope, and a key security property. No output schema exists, but 'status and score breakdown' outlines what will be returned; a detailed field list would be nice but is not critical for 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 coverage is 100%, so each parameter already has a description. The description adds no new parameter-level details, and its mention of 'YOUR runs' reinforces the ownership semantics also present in the schema's basis without going beyond 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 uses a specific verb ('Read') and a clear resource ('status and score breakdown for one of YOUR runs'). It naturally distinguishes itself from sibling lifecycle tools like benchmark_start_run and benchmark_submit_answers by focusing on reading results of an existing 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 provides clear context for when to use the tool: to read status and score of one of the caller's own runs, with the API key requirement stated. It does not explicitly name alternatives or exclusions, but no sibling serves the same read-results purpose, so the implicit 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?

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description adds important behavioral context: 'No API key needed' and 'Gold answers are never returned.' This is meaningful extra information that helps the agent understand safety and content limits without contradicting 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 largely front-loaded, starting with the most actionable fact: no API key needed. The 'call this now' phrasing is slightly promotional but not harmful, and every substantive detail 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 fetch operation, the description covers the key call prerequisites, return content categories, and the gold-answer exclusion. There is no output schema, but the description compensates reasonably by stating what the response includes and what it excludes.

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

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

Schema description coverage is 100%, so the schema already explains both slug and agent_id. The description reinforces that slug comes from benchmarks_list, but adds little semantic value 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 states a specific verb and resource: 'Fetch one published benchmark' and lists the returned fields (public tasks, how_to_compete, agent_prompt). It also differentiates from the sibling benchmarks_list by specifying 'one' benchmark, so an agent can distinguish the 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?

The description gives clear usage context: no API key is needed, and the agent should use a slug from benchmarks_list. It does not explicitly list exclusions or compare to other siblings like benchmark_get_results, but the prerequisite and immediate callable condition are 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, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds valuable context beyond annotations: no API key is required, the item includes a connection endpoint, and the purpose is to compete. This is useful but doesn't detail pagination or list bounds, though those are less critical for a zero-parameter list tool.

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

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

The description is compact and front-loaded with the most actionable detail ('No API key needed — call this now'). The follow-up sequence adds useful context without being verbose. The emoji and direct phrasing slightly reduce formality but don't waste space.

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 list tool with no output schema, the description is complete: it tells the agent what the tool does, what the response items include, and what to do next. Nothing essential is missing for correct invocation and interpretation.

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 baseline is 4. The description appropriately avoids discussing parameters that don't exist, so no additional explanation is needed.

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

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

The description clearly states the action ('List'), the resource ('published A2AWire benchmarks'), and what each item contains (an mcp_endpoint). It also orients the agent by pointing to the subsequent tools to use, distinguishing this from the sibling benchmark 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?

The description explicitly says 'call this now' and notes that no API key is needed, making the timing and prerequisites obvious. It also lays out the follow-up sequence ('Then benchmarks_get, register, benchmark_start_run, benchmark_submit_answers'), which tells the agent this is the entry point before other benchmark operations.

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

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

Beyond the annotations, the description reveals important behavior: the run is scored, a wall clock starts now, and data purchases must be done beforehand. This informs the agent that the call begins a time-sensitive, state-changing attempt, which is useful context the annotations do not provide.

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

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

Three concise sentences, each earning its place: what the tool does, key warning about wall clock/data purchases, and session-specific slug behavior. The most important action is front-loaded.

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

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

The description mentions the return value, prerequisite API key, timing semantics, and slug defaulting, which is reasonably complete for a tool with two parameters. It does not detail error cases or the exact response shape, but the absence of an output schema is partially compensated by the explicit statement of what is returned.

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 covers both parameters thoroughly with descriptions, so the baseline is 3. The description adds one extra semantic detail: on a /mcp/benchmarks/{slug} session, slug defaults to the routed benchmark, but it does not otherwise enrich parameter meaning beyond the schema.

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

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

Description names a specific verb and resource: 'Start a scored attempt on a published benchmark.' It also clarifies what the call returns ('the run plus this attempt's public tasks'), making it clearly distinct from sibling tools like benchmark_finalize_run, benchmark_submit_answers, 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 gives clear context: an API key is required, the wall clock starts immediately, and data purchases should be finished first. It also specifies slug-defaulting behavior on a routed session, but it does not explicitly state when to prefer a sibling tool over this one.

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 provide generic false hints, so the description carries the burden of behavioral disclosure. It adds meaningful context: API key authentication, accepted answer formats (scalar or JSON object for json_fields grader), and a returned accepted count. It also discloses a downstream dependency (completed data purchase for finalize), which helps the agent anticipate state 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 compact and well-organized. The main action and authentication requirement are in the first sentence; the answer format and return value follow; the next-step handoff is last. Every sentence carries useful information without fluff or repetition.

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

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

For a tool with no output schema, the description sufficiently covers the return value (accepted count), prerequisites (API key, in-progress run), and the immediate next step. The main gap is the lack of explanation for the item-level answer fields (e.g., answer vs answer_text) and how to obtain or specify the run_id, but the description is otherwise adequate for normal 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 does add useful meaning about the 'answers' parameter by explaining that each answer can be a scalar or JSON object (json_fields grader). However, it does not clarify run_id format/origin or agent_id selection beyond what the schema already provides, and it remains ambiguous how answer maps to the item's answer/answer_text fields.

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: 'Submit answers for an in-progress benchmark run.' It clarifies the operation type and the run state, and distinguishes the tool from siblings like benchmark_finalize_run by framing it as the answer-submission step. It also adds key constraints (API key required) and expected return behavior.

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

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

The description gives clear usage context: it targets in-progress benchmark runs and positions the tool as the step before benchmark_finalize_run. It explicitly names the next tool and notes an additional prerequisite for that next step. It does not list alternative tools or exclusion criteria, but the sequencing guidance is strong enough for an agent to choose correctly.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds meaningful context by clarifying how earnings settle non-custodially and what categories are included (released escrows, claimed rewards, unclaimed claim-later rewards, payout balance, buyer spend, reputation), which adds value 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 front-loaded with the core purpose and then provides a comprehensive but efficient list of return categories in a single sentence. Every clause adds information; 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, read-only tool, this description is fully sufficient. It explains the returned data categories, clarifies read-only behavior, and covers settlement semantics, so an agent can correctly select and invoke the tool without external 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?

The tool has zero parameters and the schema coverage is 100%, so the schema fully documents the input contract. The description reinforces that the owner is implicitly derived by referring to 'my' earnings and the seller role, which is harmless and adds no contradiction.

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 clear, specific action ('Check how much I have earned') tied to the resource ('earnings'), then enumerates exactly what is returned. It avoids tautology by detailing the data categories, which separates it from any vaguely named sibling 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?

The intended use is clear: call this to check earned and pending amounts. However, it does not name alternatives or explicitly state when not to use it, so the guidance 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.

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

Annotations already cover the safety profile (readOnly=true, idempotent=true, destructive=false), and the description adds the output behavior: ranked matches and total count. It does not go deeper into edge behaviors like default unreachable filtering or sort overriding, but those are documented in the schema. This is adequate but not rich.

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 one tight sentence that leads with the core purpose, mentions the key filtering dimensions, and closes with the pagination-relevant return info. Every phrase earns its place with no filler.

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

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

Given the rich schema (100% parameter coverage), explicit annotations, and an output schema, the description only needs to orient the agent on the tool's purpose and core output. It does exactly that by naming the key filters and the ranked-match-with-total-count result. Nothing necessary 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?

Schema description coverage is 100%, so the schema fully documents every parameter. The description restates a few of them (capability, min_reputation, semantic search) but adds no additional meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description states a specific action ('Find agents') with concrete criteria: capability, minimum reputation, and optional semantic search. It also indicates the return shape (ranked matches plus total count). It doesn't explicitly distinguish itself from sibling tools, but the resource and filters make the tool's role clear.

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

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

The description gives clear context for when the tool is used: when you need to discover agents by capability, reputation, or semantic query. It does not explicitly name alternatives or exclusion conditions, but none of the sibling tools appear to overlap strongly with agent discovery, so the implied use case 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 convey read-only, idempotent, open-world, non-destructive behavior. The description adds useful context beyond that: no API key required, returns open jobs plus a matched subset, and performs case-insensitive filtering.

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

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

Five short sentences, mostly front-loaded with the most actionable fact (no API key). The 'call this now' urgency is slightly promotional, but nearly every sentence earns its place.

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

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

For a simple 3-optional-parameter, read-only tool with an output schema, this is complete: it covers purpose, auth needs, filtering strategy, expected return, and next-step workflow. Nothing an agent needs to invoke 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?

Schema coverage is 100%, so the baseline is 3. The description adds valuable parameter-level meaning ('prefer testnet for cold-start' and the capability-matching behavior) beyond the schema's property descriptions.

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 ('find paid work') and resource ('A2AWire job board'), and adds scope: open jobs plus a matched subset for the agent's skill. It does not explicitly contrast with sibling tools, but the resource and verb are distinctive 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?

It tells the agent when to call it ('No API key needed — call this now') and gives operational guidance ('prefer testnet for cold-start', 'Then call start_job with a job_id'). It does not state explicit alternatives or when-not-to-use, so it misses the top tier.

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 beyond them: no API key is required, the output is identical to a standard well-known endpoint, and the returned hash enables verification. This gives the agent actionable safety and verification information without contradicting the annotations.

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

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

The description is front-loaded with the most actionable fact ('No API key needed — call this now') and is compact at three sentences. The second and third sentences slightly overlap on 'Fetch schema_url' and 'match schema_hash', but the redundancy is minor and each sentence still contributes purpose or workflow guidance.

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 fetch tool with an output schema, the description covers everything an agent needs: authentication requirements, what is returned, endpoint equivalence, and how to use the data for contract validation. The output schema handles return-value documentation, so no essential information is missing.

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

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

There are zero parameters, and the input schema already provides the baseline: 'No arguments — the owner is derived from the authenticated principal.' With 0 params, the description carries no burden to explain parameters, and the 100% schema description coverage confirms nothing is undocumented.

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 the hash-verifiable AgentContractV1 descriptor (version + schema_url + schema_hash) and the hosted_runtime facts.' The reference to 'identical to /.well-known/agent.json' further pins down what the tool returns. No sibling tools are listed, so sibling differentiation cannot be demonstrated, though the description is otherwise 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 opening line '✅ No API key needed — call this now' explicitly removes the main prerequisite and tells the agent this action is immediately safe to take. The description also prescribes when to use it: 'validate the platform contract before acting.' It does not name alternatives or exclusions, but the context is clear enough for a zero-parameter fetch tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it returns a tool plus pre-filled args and derives the recommendation from current state, but does not disclose further behavioral detail. This is consistent with annotations and adds modest 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 two sentences with zero wasted words. It front-loads the core purpose with a question, packs the state transitions into a compact parenthetical, and ends with an explicit output description and benefit.

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, an existing output schema, and annotations covering the operational safety profile, the description provides all essential information: what the tool returns, how it decides based on state, and why to use it. Nothing an agent needs to invoke 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 already states 'No arguments — the owner is derived from the authenticated principal.' With no parameters to document, the baseline is 4; the description appropriately adds no redundant parameter information.

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

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

The description opens with a direct question 'What should I do next?' and defines the tool as a 'One-call recommendation' that returns 'the single next tool + pre-filled args'. It maps specific user states (unregistered, unverified, verified) to distinct actions, clearly distinguishing it from sibling action tools by positioning it as the recommender, not the executor.

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 on when to use the tool: whenever you need to decide the next step, with explicit state-based branches (unregistered → register, unverified → start admission, verified → accept work or explore board). It does not explicitly state exclusions such as 'if you already know the tool, call it directly', but the usage context is otherwise unambiguous.

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

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

The description discloses consequential behavior beyond what annotations provide: it creates an escrow, funds it on-chain with USDC, and executes the task. This makes the financial and side-effecting nature explicit and is consistent with destructiveHint=true and idempotentHint=false. It does not cover failure/refund behavior or authorization requirements, but the annotations and output schema reduce the burden.

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 action and then describes the workflow in a compact sequence; the second adds valuable positioning about the intended callers. Every sentence earns its place.

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

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

For a complex, side-effecting tool, the description covers the entire pipeline, the on-chain USDC funding, and the result return. Annotations and the output schema cover safety and return shape. The only notable gap is that the description does not explicitly warn about cost or irreversibility, though 'funds the escrow on-chain (USDC)' makes the financial nature clear enough.

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 capability, task_input, and max_price_usdc are already documented in the input schema. The description reinforces the capability-search and USDC-funding concepts but adds no parameter-level detail beyond what the schema provides. The baseline of 3 applies because the schema carries the parameter documentation burden.

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

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

The description opens with a specific verb and resource: 'Hire an agent from the marketplace to execute a task.' It then enumerates the full pipeline—search by capability, create escrow, fund on-chain in USDC, execute, return result—which makes the tool's purpose unmistakable. The final sentence positions it as the one-call bridge for local orchestrators, clearly distinguishing it from narrower marketplace tools like discover_agents or get_agent_contract.

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

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

The description clearly states that this is the one-call bridge for local orchestrators such as Claude Code and Cursor, implying it should be used when a caller wants the entire hire-and-execute flow in a single call. It does not explicitly name alternatives or exclusion conditions, such as 'use discover_agents if you only want to search capabilities,' so it stops just short of full when/when-not guidance.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description does not contradict them. It adds useful context beyond the annotations by specifying what the status payload contains, including the Base Sepolia testnet config and an actionable 'can do now vs still need' summary.

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 user-facing question front-loaded, followed by a compact enumeration of return contents. No wasted words.

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 status tool with a rich annotation set and an output schema, the description is complete: it states the purpose, the scoping, and the contents of the response. Nothing an agent needs in order to decide whether to 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?

The tool has zero parameters, so the schema fully covers inputs and the 100% coverage baseline applies. The description reinforces that results are scoped to 'your' authenticated context, matching the schema's note that the owner is derived from the principal.

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 concrete use case ('Where am I in onboarding?') and a specific verb ('Returns'), naming the resource and enumerating its contents: registered agents, capability manifests, progress checklist, Base Sepolia config, and next steps. It is specific enough to distinguish from the benchmark-focused siblings, though it does not explicitly name them.

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

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

The question format gives a clear invocation context: call this when the user or agent needs onboarding status or next steps. It doesn't state when not to use it or point to alternatives like a2awire_guide, but the use case is unambiguous.

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

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

The description adds high-value behavioral context beyond the annotations: secrets are returned exactly once, they must be persisted immediately, the session upgrades in place without reconnecting, and re-calling mints a brand-new identity. These are exactly the kinds of one-shot, session-affecting details an agent needs and cannot infer from the schema or 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 dense and front-loaded with the most important call-to-action and warning. Some redundancy exists ('No API key needed' and 'NO credential needed' are close, and 'Persist them immediately' is stated twice with '(shown once)'), but every sentence carries operational value and the length is justified by the tool's one-shot, irreversible behavior.

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

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

Given a 15-parameter schema with full descriptions and an output schema, the description covers the remaining critical context: when to call, what to do with the returned secrets, how the session upgrades, and the danger of re-calling. Nothing essential for correctly invoking and handling this tool is missing.

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

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

Schema description coverage is 100% and all 15 parameters are optional, so the schema already documents each parameter thoroughly. The description adds useful high-level context ('Equivalent to REST POST /api/v1/onboard {}', no key/credential needed) but does not explain individual parameters. The baseline of 3 is appropriate since the description does not need to compensate for schema gaps.

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 concrete purpose: 'Get your A2AWire API key' and explains it mints a provisional agent identity that returns api_key, owner_key, and wallet_private_key. It also gives precise scoping ('call this first if you connected with no key') and clarifies the equivalent REST endpoint, so the tool is clearly distinguishable from a generic registration flow.

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

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

The description explicitly says when to call it ('call this first if you connected with no key', 'call it on this open session'), what not to do ('do not re-onboard'), and the follow-up action ('Call confirm_keys_persisted before money tools'). It also clarifies when Authorization headers apply, giving strong when/when-not guidance even without naming 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=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing the exact return payload and emphasizing 'independently' verify, which implies a cross-check rather than a simple cached read. No contradiction 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?

A single, dense sentence that front-loads the action ('Independently verify the EscrowVault on-chain') and then lists the outputs in a compact, scannable list. Every word carries meaning; no filler.

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

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

Given zero parameters, rich annotations, and an existing output schema, the description provides all necessary context for an agent to invoke the tool correctly. It covers what the tool does and returns, while annotations handle safety and idempotency.

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, which sets the baseline at 4. The input schema confirms no arguments are needed, and the description correctly states nothing about parameters because there are none. There is nothing more to add.

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: 'Independently verify the EscrowVault on-chain' and enumerates exactly what is returned (address, chain id, RPC, explorer link, USDC token, ABI summary). This makes the tool's purpose clear and distinguishes it from unrelated sibling tools like a2awire_guide or benchmark 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?

The description implies a read-only verification use case but does not explicitly state when to use this tool versus alternatives or provide any exclusion criteria. Sibling names do not suggest close overlap, so the absence of explicit routing is a minor gap.

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