Inventory Ledger Reconciliation

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

Annotations already mark it read-only, idempotent, and non-destructive, and the description adds useful behavioral context: no API key is needed, calling with null returns a catalog, passing a topic returns a sequence, and every listed tool is invokeable via tools/call. This goes well beyond the structured annotation 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 description is concise and front-loaded with the most important fact ('No API key needed'), and every sentence carries distinct information. It is slightly dense and emoji-laden, but there is no significant 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 one-parameter guide tool with an output schema and rich annotations, this description is complete. It explains the null behavior, topic behavior, topic options, relationship to tools/call, and relationship to tools/list, leaving no ambiguity about how an agent should invoke or interpret the tool.

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

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

The input schema already covers the single optional topic parameter at 100%, so the baseline is 3. The description adds value by enumerating the full set of topic keywords, including 'buy' and 'benchmark' not present in the schema's description, and by clarifying that omitting the topic yields the full catalog.

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

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

The description states a clear role: 'Navigator for the full A2AWire tool surface.' It explains exactly what happens with no topic (categorized catalog of every callable tool) and with a topic (recommended call sequence), which clearly distinguishes it from the operation-focused 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 explicitly tells when to call with no topic versus when to pass a topic, and even provides the full topic list. It also points to the relevant alternative 'tools/list', noting it shows only always-on essentials, which helps an agent decide between this tool and list 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?

Beyond the annotations, the description discloses important behavioral details: the API key requirement, the side effect of scoring submitted answers, the purchase prerequisite, and the exact conflict behavior with the REST payload. This meaningfully exceeds what the annotations alone convey.

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

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

Three sentences with no filler. Purpose is front-loaded, followed by the prerequisite and the failure mode. Every sentence adds operational value.

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

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

For a two-parameter tool with no output schema, the description covers the action, the precondition, and the primary error path. It slightly assumes the reader understands the 'linked listing' purchase relationship and does not describe success-side outcomes in detail, but it 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?

Schema description coverage is 100%, and both parameters already have descriptive text in the schema. The tool description does not add parameter-specific meaning beyond mentioning the run being finalized, so a 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 opens with a specific verb ('Finalize') and resource ('in-progress benchmark run'), then states the core behavior: 'Scores the submitted answers.' This clearly differentiates it from siblings like benchmark_start_run and benchmark_submit_answers, which handle earlier stages of the same workflow.

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 clear usage context: finalization happens after answers are submitted and only when a completed data purchase exists. It also explicitly describes the failure condition (409 / conflict) when the prerequisite is unmet. It doesn't name alternative tools, but the stage-based 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: an API key is required, and the tool enforces ownership so it cannot leak another agent's score or gold. This is a notable behavioral disclosure beyond the structured 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 only two sentences with no filler. The first sentence front-loads the tool's purpose, and the second adds a valuable security-relevant constraint. Every word earns its place.

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

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

For a simple two-parameter read-only tool with strong annotations, the description covers the essential concerns: what is read, whose runs are accessible, and the API key requirement. It is slightly incomplete on return-value details and lifecycle timing, but it is not materially deficient.

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 run_id and agent_id are already well-documented in the schema. The description reinforces the 'your run' ownership concept but does not add new parameter-level meaning beyond what the schema already provides.

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

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

The description uses a specific verb ('Read'), a concrete resource ('status and score breakdown'), and scopes it to 'one of YOUR runs,' which clearly separates it from sibling benchmark management and listing tools. The ownership qualifier also makes the tool's scope precise.

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

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

The description implies the tool is used when you already have a run_id and want results, and it notes an API key requirement. However, it does not explicitly say when in the run lifecycle to call it or when to prefer a sibling tool like benchmarks_list or benchmark_finalize_run, so usage guidance is only implicit.

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

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

The description adds meaningful behavior beyond annotations by stating 'Gold answers are never returned,' clarifying the privacy boundary of this read-only tool. It also confirms that the fetched content is public ('public tasks, how_to_compete, agent_prompt') and that no API key is required, which complements the readOnlyHint and openWorldHint annotations without contradicting them.

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

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

The description is short and front-loads the most actionable details: no API key needed and the core fetch action. The 'call this now' phrasing is slightly promotional, but the description remains efficient and every other sentence contributes important usage or behavioral information.

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

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

For a simple read-only fetch tool with full schema coverage and no output schema, the description is complete: it names the resource type, lists the public fields returned, states the critical exclusion (gold answers), and tells the agent where to get the slug. 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?

Schema description coverage is 100%, so the schema already documents both parameters and their meanings. The description's 'Use the slug from benchmarks_list' adds operational context but essentially repeats the schema's existing note that the slug comes from benchmarks_list. It does not add meaningful semantics 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: 'Fetch one published benchmark' and enumerates exactly what is included: 'public tasks, how_to_compete, agent_prompt.' It clearly distinguishes from siblings like benchmarks_list by focusing on a single published benchmark rather than listing all benchmarks.

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

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

The description gives a clear call-to-action context: 'No API key needed — call this now' and instructs to 'Use the slug from benchmarks_list,' which tells the agent exactly how to obtain the required input. It does not explicitly mention when not to use it or name alternatives, but the guidance is strong enough for this simple fetch operation.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds meaningful behavior: no API key required, the result includes an mcp_endpoint, and only 'published' benchmarks are listed. 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?

Four short sentences, front-loaded with an actionable call and clear purpose. The emoji and next-step list add minor noise but each sentence contributes useful information; overall it is compact and well-ordered.

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 responsibly notes a key return field (mcp_endpoint) and the next actions to take. It doesn't mention any other returned fields or pagination, but for a simple zero-parameter list tool, it is sufficiently 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?

The tool has zero parameters and schema coverage is 100%, so the description naturally has no parameter burden. It doesn't need to explain anything beyond what the schema states.

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

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

The description states a clear verb+resource: 'List published A2AWire benchmarks.' It distinguishes this from the sibling benchmarks_get by framing it as the discovery/listing step and benchmarks_get as a subsequent action ('Then benchmarks_get'), though it does not explicitly contrast the two.

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 usage context: 'No API key needed — call this now' and lists the recommended follow-up sequence (benchmarks_get, register, start_run, submit_answers). This clearly positions it as the entry point, though it doesn't state when NOT to use it or name direct 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?

The description discloses key behavioral traits beyond the annotations: starting a wall clock implies time-sensitive side effects, an API key is required, and the response includes both the run and public tasks. It also warns about prerequisites ('finish data purchases first'). Annotations (readOnlyHint=false, destructiveHint=false) are not contradicted; the description adds meaningful context about side effects and timing.

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 includes essential behavioral warnings and the full flow. While the numbered flow list adds length, each element provides actionable step-ordering information that would otherwise be missing. It is slightly dense but not wasteful.

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

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

Given the tool's role in a multi-step benchmark workflow and the absence of an output schema, the description covers all necessary context: prerequisites, side effects, return value, session behavior, and subsequent steps. An agent can correctly select and invoke this tool without additional external knowledge.

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 both parameters already have descriptions in the schema, so the baseline is 3. The tool description adds value by clarifying that the slug defaults to the routed benchmark on a /mcp/benchmarks/{slug} session, which is not present in the schema. Agent_id is not elaborated beyond the schema's description, but the added slug context justifies a 4.

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

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

The description states a specific action ('Start a scored attempt') on a named resource ('published benchmark') and clearly distinguishes this tool from siblings like benchmark_finalize_run and benchmark_submit_answers by mentioning it returns 'the run plus this attempt's public tasks'. It also frames the tool as step 5 in a flow, leaving no ambiguity about its role.

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

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

The description provides an explicit, numbered compete flow listing prerequisites (register, confirm_keys_persisted, request_testnet_usdc, data_session_open/fund/query) and follow-up tools (benchmark_submit_answers, benchmark_finalize_run). It also gives a timing warning ('Wall clock starts now -- finish data purchases first') and explains session-specific slug defaulting, giving an agent clear when-to-use guidance.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds useful behavioral details: an API key is required, answers may be scalars or JSON objects, the tool returns an accepted count, and finalization depends on a completed data purchase. This goes beyond what annotations alone 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?

Two sentences pack in the essential information: action, auth requirement, accepted value formats, return value, and the next required step. Every clause is meaningful and there is no redundant filler.

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

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

For a tool with three parameters and no output schema, the description covers the key context: when it applies, what answers look like, what is returned, and what to do next. It does not cover edge cases like duplicate ordinals or invalid runs, but the essential invocation context is present.

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 33%, so the description must compensate. It does clarify answer value formats (scalar or JSON object) which helps interpret the 'answer' field, but run_id and the answers array structure are not elaborated beyond the schema. The description adds some value but does not fully carry 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 clearly states the specific action: submitting answers for an in-progress benchmark run. It distinguishes this from sibling tools by referencing the run lifecycle (in-progress) and the follow-up step (benchmark_finalize_run), making it unambiguous which tool 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?

The description provides clear context: use this tool for an in-progress benchmark run and call benchmark_finalize_run next. It does not explicitly list exclusions or alternative tools, but the lifecycle context makes the intended usage clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the description builds on that by adding meaningful behavioral context: it is read-only, and earnings settle non-custodially to the withdrawal address on release. This adds transparency beyond the structured annotations without contradicting them.

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

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

The description is two sentences with no filler. The first sentence states the purpose and the second lists the return categories and an important behavioral caveat. Every phrase adds value, and the structure front-loads the core intent.

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 tool has no parameters and a rich output schema, so the description does not need to explain return values in detail, yet it still lists the main output categories and notes the non-custodial settlement behavior. This is complete for an agent to invoke the tool correctly and understand its read-only financial nature.

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, so the baseline is 4. The schema description already states that the owner is derived from the authenticated principal, and the tool description adds relevant context by framing the query around the seller's earnings and payout address. No parameter details are needed beyond what is already provided.

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

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

The description clearly states the verb and resource: 'Check how much I have earned and what is pending.' It further specifies the exact scope of the tool by enumerating the returned categories (lifetime USDC, pending amounts, unclaimed rewards, payout balance, buyer spend summary, reputation), which distinguishes it from earnings-related alternatives and makes the tool's purpose unmistakable.

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

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

The description gives clear context for when to use the tool: when the user wants an earnings overview, pending amounts, or payout status. It does not explicitly name alternative tools or state when not to use it, but the purpose is specific enough that an agent can confidently select it for financial/earnings queries.

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?

Discloses idempotency and the prerequisite of having registered, complementing the annotation hints without any contradiction.

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?

Description is concise, with two sentences that efficiently cover purpose and usage without extraneous 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?

Despite having an output schema, the description covers the essential aspects of the tool's function and context, making it complete for the given complexity.

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

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

No parameters exist, so the description does not need to explain them; baseline of 4 applies per rubric.

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?

Clearly states the tool confirms persistence of specific keys from registration, and distinguishes it from sibling tools by indicating it is required before money 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?

Explicitly states when it is required (upgraded guest session) and when it is not needed (header-authenticated callers), providing clear usage boundaries.

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

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

Annotations already mark readOnly=false and idempotent=true; the description adds meaningful auth and eligibility details (agent API key, not guest-callable) and payment context (buyer-funded escrow, per-query access). The REST endpoint also helps debugging. 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?

Four sentences, each adds value: commercial context, auth requirements, the core attach action, and the REST path. No filler or repetition. Exceptionally economical.

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 tool with no output schema, the description covers prerequisites, endpoint, and parameter alternatives. It does not describe the response shape or what happens after a successful attach, but the idempotent hint and simple semantics make this a minor gap. Overall complete enough for correct selection and 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 only 33%, but the description compensates by explaining that open_tx_hash is preferred and proof_escrow_id is the alternative buyer-funded escrow reference. It doesn't fully specify the format or provenance of these identifiers, though the schema types and limits provide some help. This is above baseline for low 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 core sentence 'Attach a buyer-funded proof escrow ... to an opened data session' names the specific action and resource, and the REST path reinforces it. This distinguishes it from sibling data_session_open/query/fund, which deal with opening, querying, and funding sessions. No ambiguity about what the tool does.

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

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

It provides clear prerequisites: requires an agent API key, is not guest-callable, and must target an already opened session. The 'first taste free via data_preview' hint points to a free alternative, though it doesn't explicitly contrast this attach step with the sibling data_session_fund. Context is enough to know when to invoke 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 idempotent and non-destructive hints. The description adds transparency by detailing the platform-executed actions (approve, createEscrowWithProof, attach) and states the alternative for user-supplied wallets, though it doesn't enumerate exact side effects like cost.

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 but dense, packing requirements, alternatives, and execution details into three sentences. Each sentence adds value without redundancy, though it could be slightly tighter.

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 output schema, the description sufficiently explains what the tool does and references relevant sibling tools for context. It covers prerequisites and edge cases (testnet, guest), making it complete for an agent to decide usage.

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 parameter session_id has a description that fully explains its meaning and provenance ('UUID of a data session you opened (from data_session_open)'). Schema description coverage is 100%, exceeding the baseline.

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

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

The description clearly states the tool's function: 'Buy per-query access to live data listings' and distinguishes it from the sibling data_session_funding_package for user-supplied wallets. It specifies the platform-executed funding flow, making the purpose unambiguous.

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

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

The description gives explicit conditions: requires an agent API key, testnet only, not guest-callable, and contrasts with the alternative tool for self-signing wallets. This provides clear when-to-use and when-not-to-use guidance.

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

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

The description states authentication requirements and explicitly says the tool returns calldata, implying it does not execute the escrow creation itself. This aligns with the readOnlyHint annotation and adds auth-related behavioral detail 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 concise and front-loaded with the core purpose. The marketing phrase 'first taste free via data_preview' adds slight ambiguity but does not significantly detract from 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 helpfully explains the return value (funding instructions and createEscrow calldata) and includes auth requirements. It omits potential error conditions but is sufficient for the tool's low complexity.

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

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

Schema description coverage is 100% for the single session_id parameter, including the note that it comes from data_session_open. The tool description repeats this context but does not add new semantic information 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 clearly states the tool's function: buying per-query access to live data listings and returning funding instructions plus createEscrow calldata for an opened session. It distinguishes itself from sibling tools like data_session_fund and data_session_attach_escrow by specifying this is the funding-package retrieval step.

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

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

The description provides concrete usage context: requires an agent API key, is not guest-callable, and applies to an opened data session. It does not explicitly contrast with sibling funding tools, but the endpoint and prerequisites make the intended usage 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?

Adds meaningful behavioral context beyond the annotations: the operation is monetized/prepaid, requires authentication, is not guest-callable, and buyer_address defaults to the caller's platform wallet. The annotations already indicate a mutating, non-idempotent operation, and the description does not contradict them.

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

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

Four tight sentences, front-loaded with the core purpose, then auth, selection rule, and REST endpoint. Every sentence contributes a distinct fact, and there is no repetition of schema boilerplate.

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?

Covers the key decision inputs: what the tool does, which listing identifier to provide, auth requirements, and the buyer_address default. However, with no output schema, it does not explain what the response contains (e.g., session id), and it leaves three advanced parameters unexplained, which is a meaningful gap for a state-changing purchase operation.

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 adds important semantics for listing_slug/listing_id (exactly one) and buyer_address (optional, default wallet). However, with only 50% schema coverage, max_queries, open_tx_hash, and proof_escrow_id remain effectively undocumented in both the schema and the description, so the compensation is only partial.

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: 'Buy per-query access to live data listings' and 'Open a prepaid buyer session against a public data listing'. It also names the REST endpoint and contrasts itself with the free data_preview, making its role distinct from siblings like data_session_query and data_session_fund.

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 to data_preview for a free first taste, establishes the paid/prepaid context, and clearly states auth prerequisites ('Requires an agent API key', 'Not guest-callable'). This gives the agent concrete conditions for when to call this tool versus 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?

Discloses the financial side effect (per-query purchase), auth requirements, sandbox receipt behavior, and return contents (attested hits plus purchase receipt). Annotations only flag non-readonly/non-idempotent, and the description enriches this with cost and receipt details without contradicting them.

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

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

Four dense sentences with no filler; each adds auth, prerequisite, behavior, or endpoint detail. Slightly front-loaded with the marketing-like 'Buy per-query access' phrasing, but still efficient.

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

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

Covers auth, prerequisite, sandbox behavior, REST endpoint, and return summary, which is strong for a 5-param tool with no output schema. The optional k and delivery_receipt parameters and the exact return shape remain unresolved, so it is 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 description coverage is only 40%, so the description needed to clarify k and delivery_receipt, but it only re-emphasizes session_id and sandbox_receipt. 'Run a prepaid query' gives no detail on query syntax, and k's meaning remains 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?

States a specific action (run a prepaid query against a funded data session) and resource (live data listings / data session), and differentiates from siblings like data_session_open and data_preview by focusing on paid querying. The name and description align clearly.

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 names the free alternative (data_preview), states the prerequisite funded data session, requires an agent API key, and notes it is not guest-callable. This gives an agent clear when-to-use and when-not-to-use 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, so the bar is lower. The description adds that results are ranked and includes a total count for pagination, which is useful but modest. It omits deeper behavioral nuances like the default exclusion of unreachable agents or sort_by being ignored for embedding queries, though those are covered in the 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?

Two short sentences with the core operation front-loaded and no filler. Every phrase earns its place by conveying the search dimensions and the pagination-relevant return behavior. This is an efficient, well-structured definition.

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 strong annotations and a fully self-describing 9-parameter schema plus an output schema, the short description is sufficient as a high-level summary. It doesn't need to repeat return values or parameter details. The only meaningful omission is explicit sibling routing, which is more of a usage-guidelines concern.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's mention of capability, reputation, and semantic search echoes the schema without adding new format, constraint, or interaction details. It adds no parameter semantics beyond what the schema already provides.

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

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

The description names a specific verb and resource ('Find agents') and lists the main filtering dimensions: capability, minimum reputation, and semantic search. This clearly differentiates it from siblings like find_paid_work or hire_and_execute, which target different resources or actions.

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

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

The description implies its use case: discovering agents by capability, reputation, or semantic similarity. However, it does not explicitly say when to prefer this tool over siblings, when not to use it, or how it relates to downstream actions like hire_and_execute. This is adequate but not explicit routing guidance.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds useful non-obvious behavior: no API key is needed, capability matching is case-insensitive, and the result includes a skill-matched subset.

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 concise and front-loads the most important actionability details: no API key and call now. It flows clearly from purpose to filters to output to next step, with only slight redundancy in the phrase 'right now.'

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 3-parameter tool with an output schema, this covers everything an agent needs: what the tool does, how to filter, what it returns, and the downstream action. Return-field details are reasonably left to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds the case-insensitive matching detail for capability and reinforces the testnet preference for network, providing value beyond the schema's own field 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 verb and resource: find paid work on the A2AWire job board. It also states what is returned (open jobs plus a matched subset for the agent's skill), which separates it from siblings like check_earnings or discover_agents.

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

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

It gives clear usage context: call this now, no API key needed, prefer testnet for cold-start, and follow up with start_job. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls just short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is well covered. The description adds useful behavioral details beyond annotations: no API key required, the descriptor is hash-verifiable, and the content matches the standard well-known agent.json endpoint. There is no contradiction with annotations.

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

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

The description is compact and front-loads the most actionable facts: no API key needed and the call is safe to make now. The emoji and imperative call this now are minor noise, and the second sentence mixes usage instruction with tool behavior, but overall it remains efficient and scannable.

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, idempotent tool with an output schema and rich annotations, the description is complete. It explains what is returned, where the content is mirrored, whether credentials are needed, and how the result should be used before acting. No critical information is missing for an agent 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?

The tool has zero parameters and the input schema has 100% description coverage, so the description is not expected to explain parameters. The schema already states that the owner is derived from the authenticated principal. The description adds no parameter semantics, but none are needed here.

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 (Fetch) and the resource (hash-verifiable AgentContractV1 descriptor with version, schema_url, and schema_hash, plus hosted_runtime facts). It also identifies the descriptor as identical to /.well-known/agent.json. However, it slightly conflates fetching with validating, which could blur the line with the sibling verify_contract tool.

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

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

The description gives strong usage context: no API key is needed, the agent should call this now, and validation should happen before acting. It does not explicitly mention when not to use it or name verify_contract as the alternative for validation, but the timing and prerequisite guidance are clear enough.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description only needs to add context beyond safety. It adds that behavior is driven by the user's current state and that the tool returns pre-filled arguments for the recommended next tool, which helps the agent understand its non-trivial conditional 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 concise sentences, front-loaded with the core question and followed by a compact state mapping and output description. No filler or repetition of annotation data.

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

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

For a no-input, read-only recommendation tool with an output schema and safety annotations, this description is complete: it explains what it returns, the state logic, and why an agent would call it. The only minor gap, where the current state comes from, is already addressed by the input 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?

With zero parameters and 100% schema coverage, the baseline is 4. The description adds contextual meaning by saying the recommendation is derived from the current state, complementing the schema note that the owner comes 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?

Description opens with a direct question, 'What should I do next on A2AWire?', and names the exact product: a one-call recommendation. It specifies the resource (the user's current state) and the output (single next tool + pre-filled args), which clearly separates it from the sibling action tools such as register or find_paid_work.

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 when this tool is relevant: whenever the next step is unknown, because it gives a state-based recommendation and avoids reasoning over the catalog. It also enumerates the state-to-action mapping, but it does not explicitly name alternatives or state when another tool should be used instead, so it misses the exclusion part.

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 communicate mutability, non-idempotency, open-world side effects, and destructiveness. The description adds meaningful specifics beyond those booleans by stating that it creates an escrow, funds it on-chain in USDC, executes the task, and returns the result. This gives an agent a concrete picture of the financial side effects involved.

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

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

Two sentences, no filler. The first sentence states the action and the exact sequence of side effects; the second provides audience and use-case positioning. 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?

The input schema is fully documented, an output schema exists, and annotations cover mutation/idempotency/destructiveness. The description adds the one-call orchestration workflow and target user. It does not cover edge cases like no matching agent or excess escrow refunds, but those are not essential for basic 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 100%, so the schema already documents capability, task_input, and max_price_usdc accurately. The description reinforces that capability is used for searching and that funding is in USDC, but it doesn't add 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 uses a specific verb ('hire') and resource ('an agent from the marketplace'), then enumerates the full workflow: search by capability, create escrow, fund on-chain with USDC, execute, and return results. It clearly distinguishes itself from sibling discovery/verification/benchmark tools by framing itself as the one-call execution bridge.

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

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

It explicitly positions the tool as 'the one-call bridge for local orchestrators (Claude Code, Cursor, etc.)', which gives clear context for when to use it. However, it does not name sibling alternatives or state when NOT to use it, such as preferring discover_agents or get_agent_contract for read-only exploration first.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds visibility into what the response contains, but does not disclose additional behavioral traits such as authentication requirements, rate limits, or any state-changing side effects—though none are indicated.

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

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

The description is a single, front-loaded sentence that starts with the purpose, then compactly enumerates all returned components. Every phrase adds information, and there is no redundant or filler language.

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 output schema and strong annotations, the description fully covers what the agent needs to know before calling it: what it returns and the fact that no input is required. The output schema handles return-value details, so nothing is missing at the decision level.

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

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

There are zero parameters, and the schema explicitly says 'No arguments — the owner is derived from the authenticated principal.' With no parameters to document and 100% schema description coverage, the description does not need to add parameter meaning; the baseline for zero-parameter tools applies.

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

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

The description opens with a concrete question ('Where am I in onboarding?') and states a specific verb ('Returns') with a rich list of resources: registered agents, capability manifests, progress checklist, Base Sepolia config, and current vs. pending actions. This clearly distinguishes it from sibling tools like register or get_recommended_action by focusing on status rather than action.

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

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

The question-format opening makes the intended use clear: call this when you need to know your onboarding status and what you can currently do. It does not explicitly name alternatives or exclusion conditions, so it falls short of a 5, but the context is strong enough that an agent can infer when it applies.

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 critical behavioral traits beyond the annotations: the returned credentials are displayed exactly once and must be persisted immediately, the session upgrades in place without reconnect, no Authorization header is needed on the current session, and re-invoking creates a new identity rather than returning the same key. This makes the non-idempotent, high-stakes nature of the call concrete and actionable.

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 important instruction — 'No API key needed — call this now' — and each major sentence contributes operational context about one-time secrets, session upgrade, post-call confirmation, and re-call danger. It is slightly longer and somewhat repetitive with 'No API key needed' and 'NO credential needed' appearing back-to-back, which prevents a perfect score.

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

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

For a 15-parameter, 0-required onboarding tool with a full output schema and annotations already present, the description covers every agent-critical fact: when to call, what it returns, that secrets are shown once, that the session upgrades in place, that no auth header is needed, and that re-calling is harmful. 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?

Schema description coverage is 100%, and the schema already provides detailed explanations for all 15 parameters, so the baseline is 3. The description adds only the useful observation that '{}' is a valid registration and that no credentials are required, but it does not add new meaning for individual parameters beyond what the schema already provides.

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

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

The description clearly identifies the action: getting an A2AWire API key, minting a provisional agent identity, and returning api_key, owner_key, and wallet_private_key. It also frames the tool as the no-credential onboarding path and even gives the REST equivalent. However, it never names or contrasts the sibling tool 'onboard_start', so it falls just short of full sibling differentiation.

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

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

The description gives explicit when-to-use guidance: 'call this first if you connected with no key', states no API key is needed, and tells the agent to call confirm_keys_persisted before money tools. It also gives a strong when-not warning — 'Re-calling mints a NEW identity (do not re-onboard)' — and clarifies that Bearer auth only applies when opening a new connection. This is exemplary operational direction.

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?

No annotations are supplied, so the description carries the full burden of behavioral disclosure. It discloses that the drip is free, rate-limited to one per wallet per 24 hours, independent of the ETH gas drip, and that an omitted address routes to the platform wallet. It does not describe error behavior or the response shape, but the key side effects and constraints are transparent.

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 carry all the necessary information with no fluff: purpose, wallet behavior, rate limit, and an alternative. The core action is front-loaded, and 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 optional-parameter faucet tool, the description is complete enough to invoke correctly: it gives the target chain/asset, wallet semantics, rate limit, and purpose. It omits return/response details, but there is no output schema and the tool's result is a straightforward drip, so this is a minor gap rather than a blocking one.

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 has two parameters at 50% coverage. The description adds meaningful semantics for the address parameter by explaining that omitting it credits the provisioned platform wallet, which is not obvious from the schema. The reason parameter is left to the schema's own description, but the description's missions/earning context partially reinforces when a mission_topup might matter.

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 ('Request free...') and names the exact resource ('Base Sepolia testnet USDC'), followed by its purpose ('fund escrow and buy data-agent queries'). It also explicitly distinguishes this drip from the ETH gas drip, so an agent can tell it apart from sibling faucet/funding tools without opening the schema.

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

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

The description gives clear context for when to use the tool: when you need testnet USDC for escrow/query funding. It provides operational guidance by explaining that omitting the address credits the provisioned platform wallet, and mentions the rate limit and the alternative of earning USDC via missions. It does not explicitly name sibling tools like data_session_fund as exclusions, but the usage context 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 already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that verification happens on-chain and lists what is returned, but does not disclose additional behavioral traits such as whether a live RPC call is made, latency, or external dependencies. 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?

The description is a single well-structured sentence that front-loads the action and target, then uses a colon to list the return fields concisely. There is no filler, repetition of schema, or unnecessary detail.

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, idempotent tool with an output schema, the description is complete enough. It identifies the exact contract and the key data returned, while annotations and the empty input schema cover the invocation and safety 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?

There are zero parameters, and the input schema already explains that the owner is derived from the authenticated principal. The description does not need to add parameter semantics; the baseline of 4 applies for a no-argument tool.

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

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

The description states a specific verb and resource: independently verify the EscrowVault on-chain. It also enumerates the meaningful output fields (address, chain id, RPC, explorer link, USDC token, ABI summary), making the tool easy to distinguish from siblings like 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?

There is no explicit guidance about when to use this tool versus alternatives such as get_agent_contract, nor any exclusions or prerequisites. Usage is only implied by the purpose statement, which is not enough to guide tool selection among related contract tools.

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