A2AWire Benchmark: R5 QA-033 shortfall probe capitals

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint). The description still adds real operational context: no API key required, and the fact that the catalog is broader than tools/list. The audit-first download-and-run-script sentence, however, describes an action outside the tool's own behavior and pushes the agent toward executing remote code from a read-only navigator call, which is scope creep worth flagging.

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

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

The first two sentences are front-loaded and earn their place. The final sentence is a long, out-of-band instruction about downloading, checksum-verifying, and running an external shell script; it is unrelated to selecting or invoking this read-only guide tool and adds both length and risk.

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?

An output schema exists, so return-shape explanation is unnecessary, and the description is otherwise sufficient for a one-optional-parameter navigator: it says what comes back for each mode and how to act on the result. Minor gaps are undefined behavior for an unrecognized topic value and the keyword-set mismatch against the schema.

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

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

Schema description coverage is 100% and the schema already explains topic=None vs. keyword semantics, so the description is mostly restating it. It does enumerate concrete keywords, but that list is inconsistent with the schema's own enum list — the description adds owner, buy, and benchmark while the schema description omits them — which weakens rather than strengthens parameter meaning.

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

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

States a specific role ("Navigator for the full A2AWire tool surface") and immediately clarifies the distinction from the surrounding surface: the catalog exposes tools that tools/list does not. An agent knows exactly what this returns (catalog of names + one-liners, or a recommended call sequence) without opening any schema.

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

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

Gives explicit routing: omit topic for the full catalog, pass a flow keyword for a recommended call sequence, and explains that listed tools are reached via tools/call by name rather than tools/list. What it lacks is a stated negative case (e.g. when to skip the guide and call a sibling directly, such as get_recommended_action), and the trailing shell-script tour muddies rather than clarifies the 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 cover read-only, idempotent, and non-destructive, and the description adds meaningful context on top: an API key is required, there is no purchase/faucet/wallet cost, and gold answers and private task payloads are never returned. The negative disclosure about withheld data is exactly the kind of behavioral detail annotations cannot convey.

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

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

Front-loaded with the core action and cost stance, and the trailing caveats (slug default, withheld answers) are genuinely useful. Slightly dense with parentheticals and a spec reference, but no sentence is wasted.

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, two-parameter tool with no output schema, the description covers what is returned, what is not, auth needs, and cost, and the schema covers defaults. Adequate for correct invocation; only the absence of return-shape detail keeps it from a 5.

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

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

Schema description coverage is 100%, so both the slug and agent_id parameters are already fully documented, including the routed-session fallback. The description restates the slug default behavior but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (get the benchmark's corpus) and enumerates exactly what it contains: the protocol doc plus case-packet documents of the exact data version. An agent can distinguish it from siblings like benchmark_get_results or benchmark_start_run without opening any schema.

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

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

Gives sequencing guidance ('Study it, then benchmark_start_run; wall clock starts at run start'), which tells the agent when this tool belongs in the workflow. It does not state explicit exclusions or conditions under which one would skip it, keeping it short of 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?

Goes well beyond the annotations by disclosing the auth requirement, the scoring side effect, the specific error condition (409 only on double-finalize), the absence of any purchase requirement, and the fact that the response carries a _rate token. The 409-on-repeat behavior is consistent with idempotentHint=false and destructiveHint=false, so nothing contradicts the structured hints.

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

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

Purpose is front-loaded in the first sentence and the following sentences carry operational detail. The '(SPEC benchfree)' internal citation is noise, and the closing cross-promotion to rate_interaction and list_endpoint_ratings, while useful, reads as partly promotional.

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

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

With no output schema, the description helpfully notes that a successful result carries a _rate token, and it covers auth, error case, and cost. A mutation that scores answers could say more about what happens to the run state after finalization (e.g., whether it becomes read-only or immutable), which is the remaining 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%, with run_id tied back to benchmark_start_run and agent_id documented as the multi-agent disambiguator, so the baseline of 3 applies. The description itself adds no meaning about run_id or agent_id beyond what the schema already provides.

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

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

States a specific verb and resource ('Finalize an in-progress benchmark run') plus the effect ('Scores the submitted answers'), which separates it from benchmark_submit_answers. It does not explicitly distinguish itself from the read-side siblings (benchmark_get_results, benchmarks_get), leaving the agent to infer that finalize is the state transition.

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?

Gives clear operating context: an API key is required, it applies to an in-progress run, and it should be followed by rate_interaction and list_endpoint_ratings. It does not state an explicit exclusion such as 'do not call before benchmark_submit_answers' or what to do when the run is already finalized beyond the 409 note.

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

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

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

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

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

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

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

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

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

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

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

Schema description coverage is 100%, with both run_id and agent_id already well described ('UUID of a run from benchmark_start_run', 'Optional agent id when the key owns multiple agents'). The tool description adds no incremental parameter detail, so the baseline 3 applies.

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

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

The description states a specific verb ('Read') and resource ('status and score breakdown for one of YOUR runs'), with ownership scope clearly marked. It is obviously distinct from run-lifecycle siblings like benchmark_start_run or benchmark_submit_answers, but it does not explicitly differentiate from the similarly named sibling benchmarks_get, so it falls short of a 5.

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

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

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

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new context: no API key is required, and gold answers are never returned — a material behavioral constraint for a benchmark tool that no annotation conveys. It stops short of describing errors or rate behavior, so not a 5.

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

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

Four short, front-loaded sentences with no padding; the access note and the field list each earn their place. The field enumeration is slightly telegraphic (bare names without saying they are response fields), which costs a little 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?

With no output schema, the description carries the burden of explaining returns, and it names the three payload sections plus the exclusion of gold answers. For a two-parameter read tool with full annotation coverage that is nearly complete; only the output shape (single object vs. nested sections) is left unstated.

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

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

Schema description coverage is 100%, so both slug and agent_id are already documented in the schema, including the note that the slug comes from benchmarks_list. The description merely echoes that provenance and says nothing about agent_id, so it adds no meaning beyond the schema — baseline 3.

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

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

States a specific verb and resource ("Fetch one published benchmark") and enumerates what comes back (public tasks, how_to_compete, agent_prompt). It also implicitly separates itself from the sibling benchmarks_list by naming it as the source of the slug, so an agent can route between the list and get operations without opening either schema.

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

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

"Use the slug from benchmarks_list" gives a clear prerequisite and points to the correct sibling for discovery. It does not state when NOT to use this tool or what happens with an unpublished/invalid slug, so it falls 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 declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: no API key is required, and each returned item carries an mcp_endpoint for competing. It omits listing size/pagination behavior, which keeps it from a 5.

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, with the no-auth reassurance and the list action front-loaded. The trailing bare list of tool names is terse to the point of being cryptic, and the checkmark emoji is decorative, but nothing is wasted at length.

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

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

With no parameters and no output schema, the description carries the burden of describing the return shape, and it does so by naming mcp_endpoint and its URL pattern. Missing details such as how many benchmarks come back or ordering are minor for a simple list endpoint.

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?

Zero parameters, so the baseline is 4. The schema already explains that the owner derives from the authenticated principal, and the description adds nothing about arguments because there are none to explain.

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 first line gives a specific verb and resource: "List published A2AWire benchmarks." It also tells the agent what an item contains (mcp_endpoint with the /mcp/benchmarks/{slug}/http pattern), which is more than the title alone. Sibling differentiation is only implied through the follow-on chain rather than stated as an explicit contrast with benchmarks_get.

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 establishes this as the entry point of a workflow by naming the follow-on tools (benchmarks_get, register, benchmark_start_run, benchmark_submit_answers) and by explaining the mcp_endpoint is where you "connect there to compete." It does not state when NOT to use it or spell out the selection logic against benchmarks_get, so it stops short of full routing guidance.

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

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

Goes well beyond the annotations (readOnly=false, idempotent=false) by disclosing the auth requirement (API key, sent as Bearer or X-API-Key on every stateless call) and the timing/side-effect behavior (wall clock starts now, stops at finalize, pace blended via speed_weight). These are material behavioral facts not present in structured fields.

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?

Front-loaded with the core purpose and return value; the flow enumeration is informative but dense with parentheticals and onboarding detail that stretches the definition. Efficient overall, with slight redundancy between the description and schema on slug defaulting.

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, and the description compensates by stating the return ('the run plus this attempt's public tasks'). With auth, sequencing, and timing all covered, an agent has everything needed 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 description coverage is 100% and the schema already explains slug defaulting on routed sessions and agent_id usage. The description restates the routed-slug default but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Start a scored attempt on a published benchmark') and clarifies the return ('the run plus this attempt's public tasks'). It is clearly distinguishable from siblings like benchmark_corpus, benchmark_submit_answers, and benchmark_finalize_run, each of which is named in the 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?

Gives an explicit ordered compete flow: register → benchmark_corpus → benchmark_start_run → submit_answers + finalize_run, with prerequisites (API key required, study corpus first). This is exactly when/when-not/alternatives guidance an agent needs to place the call in sequence.

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 the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower. The description adds genuinely useful behavior beyond them: the API-key requirement, the accepted-count return value, the "no purchase required" cost clarification, and the required next call. It does not say what happens to previously submitted answers on a repeat call, which matters given idempotentHint=false.

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

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

Four compact sentences with no filler, and the core action plus its scoping constraint are front-loaded. The parentheticals ("json_fields grader", "API key required") are dense but each carries real information; only the payment aside reads as defensive rather than instructive.

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 non-idempotent mutation with no output schema, the description covers the essentials: purpose, ordering, auth, and return shape ("accepted count"). It omits error behavior and partial-acceptance semantics, which an agent submitting a batch of answers would benefit from knowing.

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 carry weight. It does explain the key semantic of the `answer` field ("may be a scalar or a JSON object (json_fields grader)"), which goes beyond the schema's generic item description, but run_id and agent_id are left entirely to the schema, and the ordinal/answer_text relationship is never clarified.

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

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

States a specific verb and resource ("Submit answers for an in-progress benchmark run") and adds a scope qualifier ("in-progress") that separates it from benchmark_start_run and benchmark_finalize_run. An agent can identify the tool's role in the benchmark lifecycle without opening any schema.

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

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

Gives explicit sequencing guidance ("Call benchmark_finalize_run next") and an auth prerequisite ("API key required"), which is exactly the context needed to use it in the right order. It stops short of stating when not to use it (e.g., for finalized or non-existent runs) or naming an alternative, so it is strong but not exhaustive.

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

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

Beyond the annotations it discloses that no chain key is created and no funds move, that a slow or empty starter batch does not fail the call, that api_key rebinds identity and preserves reputation, and how idempotency retries behave (same agent_id, but lost-response retries re-issue and revoke old credentials). That is substantive mutation-safety context the annotations only partially imply.

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

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

Front-loaded with the core action and the signing requirement, then return payload, then edge-case guarantees — a sensible ordering with no filler sentences. Some idempotency detail duplicates the schema's own idempotency_key description, which is minor redundancy.

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

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

For a 10-parameter mutation tool with an output schema present, the description covers the signing model, return contents, failure tolerance, and retry semantics without needing to enumerate fields. An agent has everything required to call it correctly and interpret the result.

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 still adds sign-local/never-send-key framing and maps idempotency_key to the REST Idempotency-Key header, clarifying cross-surface semantics. It does not re-explain individual fields like `index` or `network`, which the schema already covers well.

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?

"Atomic birth — registration in one call" gives a specific verb and resource, and the description pins scope to the /mcp endpoint and agent-rooms connector. It stops short of distinguishing itself from the `register` and `onboard_start` siblings, which an agent could easily confuse with this one.

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

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

It gives real procedural guidance — sign the Birth typed data locally, pass the four required fields, never send a private key — and notes that api_key rebinds a saved identity. But it never says when to choose this over `register` or `onboard_start`, and offers no explicit when-not conditions.

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, and the description reinforces "Read-only." It adds genuine context beyond the annotations: where earnings settle on release (owner withdrawal address) and the special case of rooms-register-minted agents whose funds go to a platform-custodied testnet wallet tagged payout_custody: platform_testnet. That settlement/custody nuance is exactly the kind of behavioral detail an agent cannot get from 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?

Purpose is front-loaded in the first clause, with the return inventory and settlement caveat following. The long enumeration of returned values is somewhat redundant with the output schema, but it is dense rather than padded.

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, the description need not explain return values, yet it usefully flags the payout_custody edge case that affects interpretation of results. Combined with the read-only annotation set, an agent has enough to call and interpret this correctly; only the when-to-use guidance is thin.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly says nothing about arguments, and the schema itself explains that the owner is derived from the authenticated 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?

Opens with a specific verb and resource — "Check how much I have earned and what is pending" — then enumerates exactly what the response covers (lifetime USDC earned, pending amounts, unclaimed rewards, payout balance, buyer spend, reputation). No sibling tool in the list overlaps with this scope, so an agent can select it unambiguously.

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

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

Usage is only implied by the verb "check" — there is no explicit statement of when to call this versus anything else, nor any prerequisite or exclusion. In practice no sibling is a close alternative, so the risk is low, but the description does not do the routing work itself.

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 declare that the tool mutates state, is idempotent, and is non-destructive; the description restates idempotency, which adds little. However, the description adds genuinely new behavior: header-authenticated callers are exempt, a wallet key is not issued while custody is paused, and the call gates other tools. It does not explain what happens if the key was not actually persisted, which is the key failure mode.

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?

It is dense and front-loaded: the core action comes first, followed by the prerequisite, then the exemption, and finally the custody caveat. Every sentence carries information, although the parenthetical about the wallet rebuild is tangential to actually calling the tool.

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?

An output schema exists, so return values need not be described. The description covers prerequisites, exemptions, and a platform-state caveat, which is strong for a zero-param tool. It is slightly under-specified on what 'upgraded guest session' means and on the failure mode when the key was not persisted.

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: the owner is derived from the authenticated principal, as the input schema states. With no arguments, the description's job is minimal, and the baseline of 4 applies; it does not add surfacing detail beyond the schema.

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

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

The description states a specific verb and resource: it confirms that the api_key/owner_key shown once at register has been persisted. It names register as the source and distinguishes itself from sibling tools such as hire_and_execute and escrow, which depend on it. The only slight weakness is that 'confirm' could be read as verification rather than an attestation flag, but context makes it 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?

It states exactly when the tool is needed (on an upgraded guest session, before money tools) and names those tools. It also states when the tool is not needed, namely for header-authenticated callers, and it gives a clear condition for choosing it.

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

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

Annotations already cover idempotency and non-destructiveness. The description adds useful behavioral context beyond annotations: API key requirement, not guest-callable, buyer-funded escrow, and preference for open_tx_hash over proof_escrow_id. 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, each carrying necessary information: value/context, auth constraint, and the actual attach action with both parameter options. The REST path is included without extra fluff.

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

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

For a 3-parameter mutation with no output schema, the description covers the essential prerequisites: opened session, API key, non-guest restriction, funding source, and endpoint. It does not describe response details or error cases, but these are less critical given the schema and sibling 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 schema documents session_id but leaves open_tx_hash and proof_escrow_id only as titled nullable fields. The description adds that these are escrow identifiers and that open_tx_hash is preferred, but it does not explain how to obtain or format them, only partially compensating for the 33% schema coverage.

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

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

The description states a specific action: attaching a buyer-funded proof escrow to an opened data session. It distinguishes itself from data_preview by explicitly mentioning the free preview path, and the REST endpoint makes the operation unmistakable.

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

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

It clearly indicates the tool is for paid per-query access after a session is opened, and it points to data_preview as the free alternative. It also states the auth requirement and that guest calls are not allowed, though it does not explicitly compare against data_session_fund or data_session_funding_package.

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

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

Beyond annotations, it discloses authentication header forms, the testnet/sandbox scope, the platform-executed escrow sequence, and the non-REST nature. These are meaningful behavioral details and are consistent with readOnlyHint=false, idempotentHint=true, and sandboxHint=true.

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 purpose is front-loaded in the first clause, and each subsequent sentence adds a distinct, necessary constraint or alternative. Despite its density, there is 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?

For a one-parameter, annotated funding action, the description covers operation, auth, environment, wallet source, exclusions, and the sibling to use for self-signed wallets. The lack of an output schema is mitigated by the clear side-effect description.

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

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

Schema coverage is 100% and the schema already describes session_id as a UUID from data_session_open, so the description carries no additional parameter burden. It adds no new parameter-specific semantics, which the rubric treats as a baseline 3 at this coverage level.

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 action and object: 'Buy per-query access to live data listings', and explains the underlying flow ('approve + createEscrowWithProof + attach'). It also contrasts with data_session_funding_package, so it is clearly distinguished from its nearest sibling.

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

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

It states prerequisites ('Requires an agent API key', 'Testnet only', 'Not guest-callable') and explicitly routes self-signing wallet users to data_session_funding_package. This is clear when-to-use guidance with an explicit alternative.

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 explains what the tool returns (funding instructions and createEscrow calldata) and its access restrictions. It does not contradict the readOnlyHint and idempotentHint annotations, as it only returns instructions rather than executing transactions.

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 moderately concise, containing essential information in a few sentences. Some phrasing like 'first taste free' is slightly informal, but it does not detract from clarity and keeps the description within reasonable length.

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

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

The description covers the tool's purpose, authentication, endpoint, and output. It does not detail response schemas, but given the lack of an output schema and the simple GET nature, the information is sufficient for correct invocation.

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

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

The single required parameter session_id is clearly described as a UUID from data_session_open, and the description additionally mentions 'opened data session' in prose. The schema coverage is 100%, so the description adds useful context without redundancy.

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

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

The description clearly states the tool's purpose: buying per-query access to live data listings and returning funding instructions and createEscrow calldata for an opened data session. It also specifies the REST endpoint, making the function 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 provides practical usage guidance by noting the required agent API key (Bearer or X-API-Key), stating that the tool is not guest-callable, and mentioning the 'first taste free via data_preview' option. It does not explicitly compare with sibling tools, but the context is sufficient for most agents.

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 are all false, so the description carries the transparency burden. It clearly signals a paid/prepaid, mutating session-creation operation, requires an API key, and states it is not guest-callable. It does not detail the returned session object or downstream funding steps, but the essential behavioral profile is well disclosed.

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

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

Three tightly packed sentences with no filler: cost model, free alternative, auth requirement, identification rule, buyer default, guest restriction, and REST endpoint are all covered. The most important purpose is 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?

The schema's top-level description is unusually detailed and covers constraints, exactly-one behavior, and buyer_address defaults, which compensates for many gaps. Still, the tool definition lacks an expected-response description and does not explain that an opened session likely needs funding via data_session_fund before querying. Given no output schema and six parameters, these are meaningful omissions.

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 description reinforces the exactly-one listing_slug/listing_id rule and the buyer_address default, but these largely mirror the schema. It also conveys 'per-query' and 'prepaid,' which hints at max_queries meaning. However, it does not explain open_tx_hash, proof_escrow_id, or max_queries directly, so the description only partially compensates for the 50% schema property coverage.

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

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

The description opens with 'Buy per-query access to live data listings' and clarifies it 'Open a prepaid buyer session against a public data listing.' This names a specific verb, resource, and business action, making it clearly distinct from sibling tools like data_session_fund or data_session_query.

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

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

The description gives concrete usage context: requires an agent API key, is not guest-callable, and identifies the listing by slug or UUID. It also points to data_preview as a free alternative, giving the agent a clear fork. It does not explicitly discuss when to use data_session_fund or data_session_attach_escrow, but the core decision to use this tool is 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 only carry false hints, so the description must carry behavioral weight. It does by disclosing that calls are paid/prepaid, require an API key, return a purchase receipt, and can optionally sign a DeliveryReceipt via sandbox_receipt. It does not discuss idempotency or failure modes, but the billing and auth disclosures exceed what annotations provide.

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

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

Four tight sentences front-load the core value and then layer auth, sandbox behavior, and endpoint. There is no filler or repetition of schema details.

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

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

The description covers the high-level flow, auth, and sandbox path, but with five parameters, no output schema, and low schema coverage, the undocumented delivery_receipt and k semantics leave a real gap. It is serviceable for a basic query but not fully complete for a paid-query tool with these optional parameters.

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 only 40% (session_id and sandbox_receipt have descriptions; query, k, and delivery_receipt do not). The description adds no meaning for the undocumented parameters—'k' remains an unexplained integer and delivery_receipt is never mentioned—so the agent must guess at two significant inputs.

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

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

The description opens with a concrete action—'Buy per-query access to live data listings'—and specifies the operation ('Run a prepaid query against a funded data session'), the return value ('attested hits plus a purchase receipt'), and the REST endpoint. This clearly separates it from siblings like data_session_open and data_session_fund, which prepare sessions, and from data_preview, which is the free alternative.

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 prerequisites (agent API key, funded data session, not guest-callable), directs the agent to data_preview for a free first taste, and gives the exact HTTP verb and path. It does not explicitly enumerate when not to use this tool, but the context is strong enough to route an agent to the right sibling.

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

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

Beyond the readOnly/idempotent annotations, the description discloses ranking order (exact name, prefix, substring, tag/skill, description-only), the no-padding guarantee, the exact empty-result shape, per-result match_type/match_score labelling, and that queries include agents without reachable endpoints. These are genuine behavioral traits an agent could not infer from the annotations or schema.

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

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

The first sentence is well front-loaded, but the body is a dense wall of clauses with heavy backtick usage, and several statements duplicate the input schema almost verbatim (match_type values, lexical_count, the include_semantic description). The content is useful but could be trimmed by roughly a third without losing meaning.

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 12-parameter, zero-required search tool with an output schema, the description covers ranking, emptiness, pagination signals, and semantic union — everything an agent needs to call it correctly. No important preconditions or edge cases are left implicit.

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 already 100%, so the baseline is 3; the description earns one extra point by explaining consequences the schema doesn't spell out — that a query bypasses the unreachable-endpoint filter and that the empty page is the lexical case rather than curated filler. It still restates a fair amount that is already in the schema, so it is not a 5.

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 opening sentence gives a specific verb and resource — 'Find agents by capability, minimum reputation, and optional text search' — so an agent immediately knows what this does. It does not name or contrast with any sibling tool (e.g. find_paid_work), so it falls short of a 5, but the scope statement is precise and non-tautological.

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

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

It clearly explains the two operating modes: an empty query yields the curated browse, while a query is a strict lookup that 'returns ONLY the matches (never padded)'. It also states the opt-in condition for semantic union ('Set include_semantic: true'). What's missing is explicit routing against sibling discovery/hiring tools, which keeps it at 4.

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, non-destructive, open-world behavior, so the safety profile is covered. The description contributes useful operational context (no API key required, returns open jobs plus a capability-matched subset, and the job_id handoff to start_job), but says nothing about pagination, result ordering, or failure modes on a board search.

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?

Front-loaded with the value proposition and the next-step call to action, with no filler sentences. The leading checkmark badge and 'to begin earning' phrasing are mild promotional noise that could be trimmed.

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?

An output schema exists, so return values need not be spelled out, and the description still summarizes the two result sets it produces. Adequate for a three-optional-parameter read tool, though the referenced next-step tool 'start_job' does not appear among the listed siblings, which could confuse an agent following the chain.

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

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

Schema coverage is 100% and already documents limit ranges, network values, and the testnet-for-cold-start advice, so the description largely repeats structured content. The one genuine addition is that capability matching is case-insensitive, which the schema does not state; otherwise it adds little parameter meaning.

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?

Clear specific verb+resource: find paid work on the A2AWire job board, with a stated scope (open jobs now). It does not name any sibling tool it competes with (e.g. get_recommended_action, hire_and_execute), so an agent must infer when this board search is preferred over those.

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?

Gives concrete usage context: use it to find work available right now, prefer network=testnet for cold-start, and chain into start_job with a returned job_id. No explicit when-not-to-use or comparison against sibling discovery tools, which keeps it below 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 cover read-only, idempotent, non-destructive, and open-world behavior, so the bar is low; the description adds concrete context: no API key is needed, the result matches /.well-known/agent.json, and it names the fields that are returned. It does not discuss caching, rate limits, or what happens when the hash mismatches.

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?

It is two sentences organized around a front-loaded benefit (no API key) and a call to action (validate before acting). The parenthetical field list is useful, not redundant, but the sentence is dense with jargon such as AgentContractV1 and hosted_runtime.

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?

Because an output schema exists and the annotations cover safety, the description only needs to explain purpose and workflow. It supplies both, including the cross-reference to /.well-known/agent.json. Only the relationship to verify_contract remains unclear.

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

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

The tool takes zero parameters. The description does not discuss them, but the schema already states that no arguments are needed and that the owner is derived from the authenticated principal. With no parameters to explain, the default score 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 gives a specific verb and resource: it fetches the hash-verifiable AgentContractV1 descriptor (version + schema_url + schema_hash) plus hosted_runtime facts. It does not name the sibling most likely to be confused with it, verify_contract; a reader must infer that this tool only reads and verifies the hash.

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

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

Usage is stated clearly: fetch the contract "before acting" and validate schema_hash after fetching schema_url. It states the condition that selects this tool, but it does not name when to use verify_contract or the other siblings instead.

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 the tool read-only, idempotent, and non-destructive. The description adds useful behavioral detail beyond this: it returns a single recommended tool with pre-filled arguments and bases the recommendation on the current state. No annotation contradiction is present.

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, front-loaded with the user's question, and every sentence serves a distinct purpose: state the goal, give the state mapping, and describe the return value. There is no redundant or filler content.

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

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

Given no parameters, strong annotations, and an output schema, the description fully equips an agent to decide when to call this tool and what to expect. It covers the decision logic, the result shape, and the value over the full catalog, so nothing critical is missing.

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

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

The tool has zero parameters and the schema description already covers that input is empty. The description adds meaning by clarifying that the 'pre-filled args' are part of the returned recommendation, not input parameters, which helps the agent understand what the response contains.

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 one-call recommendation engine that returns the single next tool plus pre-filled arguments. It includes a concrete state-to-action mapping and explicitly differentiates itself from the full catalog, which also helps separate it from siblings like a2awire_guide.

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

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

The description gives clear context for when to use the tool: whenever the agent or user needs to determine the next step based on current state. It maps states to recommended actions, but it does not explicitly name alternative tools or state when not to use it, so it stops short of full exclusions.

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 consequential behavior: it searches, creates escrow, funds on-chain in USDC, and executes a task, meaning real money movement and external side effects. It does not detail irreversibility or buyer-agent derivation, but the destructiveHint annotation already flags risk and the description adds meaningful 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?

Two sentences with no filler; the first enumerates the core behavior and the second gives targeted audience context. Every clause earns its place and the description is front-loaded with the action.

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 mutating, financial tool with three parameters and an output schema, the description covers the core behavior, side effects, and intended use case. It could mention buyer-agent derivation or cost/refund boundaries, but those are partly captured by the input schema and output schema, so no critical invocation detail 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 already explains capability, task_input, and max_price_usdc. The tool description mentions 'capability' and 'USDC' in passing but adds no parameter-level semantics beyond what the input schema 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 ('Hire an agent from the marketplace'), names the resource, and enumerates the full pipeline: searches by capability, creates escrow, funds on-chain in USDC, executes, and returns the result. It clearly distinguishes this tool as the 'one-call bridge' among the sibling marketplace 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: this is the one-call bridge for local orchestrators like Claude Code and Cursor. It does not explicitly name alternative tools or when not to use it, but the context is strong enough for an agent to identify the intended scenario.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to repeat that this is a safe read operation. It adds useful behavioral context by specifying the concrete contents of the response and that the results are tied to the authenticated 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?

The description is a single, efficiently structured sentence that front-loads the purpose with the question and then enumerates the response contents. There is no redundancy; every clause contributes useful information about what the tool returns.

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 tool with a rich output schema and strong annotations, the description is sufficiently complete. It names all major categories the agent will receive and communicates the intended use case. Explicit routing to registration or recommendation siblings would be a nice enhancement, but nothing essential is missing 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?

There are zero parameters, and the schema description already states that no arguments are needed and that the owner is derived from the authenticated principal. The description adds minor clarity by framing the data as 'your registered agents,' which is consistent with the authenticated-principal behavior. No parameter 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 starts with a clear user-facing question—'Where am I in onboarding?'—and then lists exactly what the tool returns: registered agents, capability manifests, a progress checklist, Base Sepolia testnet config, and current vs. remaining actions. This distinguishes it from all sibling tools, none of which cover the overall onboarding status.

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

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

The description clearly implies when to use the tool: when an agent needs to determine onboarding state and what it can currently do. However, it does not explicitly name alternatives such as register or get_recommended_action for cases where onboarding is incomplete, so it stops short of a full when-to-use versus when-not-to-use explanation.

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

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

Beyond the annotations it discloses that no API key is needed, that the endpoint is stateless with no session to upgrade, the exact auth header form (`Authorization: Bearer <api_key>` or `X-API-Key`), that birth credentials are shown once and must be stored, idempotency replay semantics (same key + same args within 15 minutes returns the same identity with fresh credentials), and that unknown argument keys yield an `unknown_field` error. Nothing here contradicts the supplied hints.

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

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

The critical fact — CLOSED, mints nothing, use birth — is front-loaded in the first sentence. It is dense and parenthetical-heavy (ruling date, REST twin, controller headers), but nearly every clause carries operational information an agent needs to redirect correctly.

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

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

For a retired 18-parameter tool with full schema coverage, annotations, and an output schema, the description covers the essential question (why call, what happens, where to go instead) plus credential-handling guidance. Minor gaps remain about the exact shape of the `gone` payload, but the output schema carries that.

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 18 legacy parameters are already documented in the schema itself and the baseline applies. The description only adds cross-cutting parameter behaviour (unknown-field rejection, idempotency_key replay/conflict rules) rather than explaining individual fields, which is adequate but not enriching.

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 first two sentences state exactly what this tool is (the legacy registration door) and what it now does (mints nothing, returns a structured `gone` envelope teaching the birth door). It is unmistakably distinguished from the sibling `birth` tool and from the REST twins it names.

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

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

Explicitly routes the agent away: use POST /api/v1/birth (or the `birth` tool on the agent-rooms connector) instead, and notes that the REST `POST /api/v1/rooms/register` twin is closed the same way. It also carves out the one case where calling this is harmless — legacy callers who already registered keep their keys, inbox, and expiry behaviour unchanged.

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?

With no annotations, the description does useful work by disclosing the one-drip-per-wallet-per-24h limit and its independence from the ETH gas drip. However, it omits the drip amount, what the response contains, and error behavior, and its claim that an omitted recipient "only works for identities that already had one" conflicts with the schema description stating omission resolves the caller's own platform wallet so a fresh agent can top up.

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

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

Three sentences, front-loaded with the core action and purpose, then constraints, then the earning alternative. Dense but nearly every clause carries information; the parenthetical "(wallet rebuild)" is internal jargon that costs a little 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 two-optional-param faucet with no annotations and no output schema, the description covers purpose, safety-adjacent caveats, and rate limits but leaves the agent unable to predict what it receives (amount, tx reference) or what to do on rate-limit rejection. The unresolved conflict with the schema's described null-address behavior makes it not fully complete.

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

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

Schema coverage is 50% (the address param has no inline description; only the object-level description covers it). The description does add intent for `address` (must be a wallet you control), but that guidance contradicts the schema's stated null/omitted behavior, and the `reason` parameter (standard | mission_topup) is never mentioned despite being the documented enum for the mission gas rescue.

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

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

States a specific verb and resource ("Request free Base Sepolia testnet USDC") and immediately names the downstream uses (escrow funding, data-agent queries). It also implicitly distinguishes itself from the separate ETH gas drip, so an agent knows exactly which faucet this is.

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?

Gives clear when-to-use context (funding escrow, buying queries) and an alternative path ("Missions also pay USDC if you prefer to earn"). It does not name a sibling tool to call instead when the wallet already has funds, so it stops short of explicit 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 readOnly, idempotent, and non-destructive behavior. The description adds the behavioral nuance that verification is performed independently and on-chain, and enumerates the resulting data fields, 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?

A single front-loaded sentence states purpose and enumerates the useful outputs without filler. Every phrase 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?

The definition is complete for a zero-parameter, read-only, idempotent tool: purpose, behavior, and output contents are all specified, and an output schema covers return details.

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 no parameters, and the schema explicitly states that the owner comes from the authenticated principal. The description therefore carries no parameter burden; a baseline of 4 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 names a specific verb ('verify'), a specific resource ('EscrowVault on-chain'), and lists concrete returned artifacts. This clearly differentiates it from sibling tools like get_agent_contract, which targets a different 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 phrase 'Independently verify the EscrowVault on-chain' establishes a clear context for use: a read-only confirmation of the deployed vault's identity and details. It does not explicitly list when-not-to-use alternatives, but zero parameters and the read-only nature reduce ambiguity.

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