Go Vulnerability Database Tracker — buy per-query in-session (govulnwatch)

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?

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: no API key required, no payment, and a cap of 20 queries/session. It does not disclose what the preview response contains or that the question field is merely echoed back rather than answered.

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 free/no-key message is stated twice ('✅ No API key needed' and 'FREE preview — no key, no payment'), and the listing price is front-loaded ahead of what the tool does. The sample questions are useful, but the sentence budget is spent partly on marketing rather than operational 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 simple two-optional-parameter read-only tool with no output schema, the definition covers access cost and rate limits, which is the main operational risk. It still omits what the returned preview looks like and how it differs from a real data_session_query result, leaving an agent unsure what it will actually get.

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 both optional parameters, so the schema already explains slug routing and that question is echoed back. The sample questions in the description loosely illustrate the question field but add no syntax or constraint detail beyond the schema's maxLength and defaults.

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

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

The description identifies the listing ('govulnwatch: Go Vulnerability Database Tracker') and calls itself a 'FREE preview', so an agent can infer it samples a paid listing. However, it never states a concrete verb or what a preview actually returns (public metadata), and the pricing line '0.01 USDC/query' describes the underlying listing rather than this tool, which muddies rather than clarifies purpose.

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?

'Try one of the sample questions now' plus 'no key, no payment' implies this is the zero-commitment entry point before paying. But there is no explicit when-to-use versus siblings like data_session_query or data_session_open, and no statement of when this tool is insufficient (e.g., needing actual paid query results).

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

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

Annotations already 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?

Annotations already provide idempotentHint=true and readOnlyHint=false. The description adds context that this is a paid transaction (0.01 USDC/query) and that it is a prerequisite for queries, which goes beyond the annotations without contradicting them. It does not detail side effects like balance checks, but the key behavioral trait (cost and purpose) is 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?

The description is two sentences and front-loads the core purpose ('Buy per-query access') before adding specifics like the listing and price. It is efficient, though the second sentence could be tightened by separating the listing info from the platform execution note, but it is not overly verbose.

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 low-complexity tool with one parameter and complete schema, the description covers the essential action, prerequisite (session from data_session_open via schema), and downstream use (data_session_query). It even includes extra context about the listing and price. No critical information is missing for an agent to call 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 single parameter session_id is fully described in the schema (100% coverage), including its type, format, and source ('from data_session_open'). The tool description adds no additional parameter-specific information, so it does not improve on the schema, matching the baseline of 3 for full schema coverage.

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

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

The description clearly states the verb 'Buy' and the resource 'per-query access to live data listings', specifies the exact listing (govulnwatch) and price (0.01 USDC/query), and distinguishes itself from siblings like data_session_open (open) and data_session_query (query) by describing its role as funding that enables queries.

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: it mentions data_preview for a free trial ('first taste free') and states that funding is required to use data_session_query. However, it does not explicitly contrast with other funding-related siblings (data_session_funding_package, data_session_attach_escrow), so it lacks a full when-not/exclusion statement.

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 description adds value by noting the prerequisite session from data_session_open and that it returns fund instructions. It does not disclose side effects beyond that, but the annotations cover the safety profile. The description is consistent with annotations (no contradiction) and adds a modest behavioral detail.

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, front-loaded with the core purpose and specific listing details. No fluff; every word earns its place. The flow hint (data_preview and data_session_open) is integrated efficiently.

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 single-parameter tool with annotations and no output schema, the description covers the essential action, the specific listing, and the flow. It doesn't detail the format of the returned fund instructions or error handling, but these are minor for a tool that returns instructions rather than executing a purchase. Overall, it's sufficiently complete for an agent to call it correctly.

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

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

Schema coverage is 100% with a clear description for session_id ('UUID of a data session you opened'). The tool description only reiterates that it comes from data_session_open, adding no new meaning beyond the schema. Baseline 3 is appropriate since the schema already fully explains the parameter.

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. It names a specific listing (govulnwatch) with price, and references data_preview for free taste and data_session_open for the prerequisite flow. This distinguishes it from siblings like data_preview and data_session_open, though not from data_session_fund explicitly.

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 some usage context: preview via data_preview, then open a session, then this tool returns fund instructions. However, it does not explicitly contrast with data_session_fund or data_session_attach_escrow, leaving the agent to infer when to choose this over those siblings. It implies a sequence but lacks explicit 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?

With all four annotations false, the description carries the burden of behavioral disclosure and does reveal the essential traits: this is a paid transaction (0.01 USDC/query), prepaid, capped at 20 queries/session, and part of a fund-then-query flow. It does not warn about non-idempotent behavior (idempotentHint=false implies a double open could create another session) or mention any escrow prerequisites.

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 zero filler: the purpose, price, listing name, query cap, free-preview alternative, and workflow sequence all earn their place, and the most decision-relevant facts (cost and cap) are front-loaded.

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

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

For a tool with no output schema and six optional parameters, the missing response shape is a real gap, and the semantics of open_tx_hash and proof_escrow_id are left to inference. The rich schema-level description backfills slug-vs-UUID and buyer_address defaults, which keeps this at minimum viable rather than lower.

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 itself already documents listing_id, listing_slug, and buyer_address including the exactly-one constraint and wallet default, and the description adds session-limit context for max_queries via the 20-query cap. However, at 50% schema coverage, open_tx_hash and proof_escrow_id remain unexplained in both the schema and the description, leaving an agent unable to determine their 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?

The description identifies a specific operational action — opening a prepaid session for the govulnwatch listing — and explicitly distinguishes it from the free data_preview path ('first taste free via data_preview'). It falls short of 5 because the lead sentence 'Buy per-query access to live data listings' frames the action commercially rather than operationally, leaving the boundary with data_session_fund implicit until the closing workflow sentence.

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 names data_preview as the free alternative and lays out the sequence 'Open a prepaid session, then fund and query,' signaling to an agent that this is step one before data_session_fund and data_session_query. It lacks explicit when-not-to-use guidance and says nothing about the escrow path, even though data_session_attach_escrow is a sibling and proof_escrow_id is a parameter.

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 aspects: per-query cost (0.01 USDC), a query limit (max 20 per session), and that it follows funding. Annotations do not indicate read-only or destructive behavior, and the description aligns with the paid/consumptive nature of the operation.

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 uses a clear three-part structure: offering, listing details, and required sequence. It avoids excessive prose but includes some redundant marketing phrasing like 'first taste free,' which slightly reduces focus.

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 absence of an output schema, the description provides sufficient context about cost, limits, the specific dataset, and the required preceding steps. It does not mention error cases or response formats, but those are not strictly necessary 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 only 40%, and the description does not compensate by explaining parameters such as query, k, or delivery_receipt. Only session_id and sandbox_receipt have schema-level descriptions, leaving multiple parameters underspecified for an agent.

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

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

The description clearly states the tool provides paid query access to live data listings, specifically the govulnwatch tracker, and references the preceding session steps. However, it uses marketing-style language ('Buy per-query access') rather than plainly stating 'run a query against a funded session,' which is only in the schema's internal description.

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 an explicit sequence: data_session_open → data_session_fund → data_session_query, and mentions data_preview for a free first taste. This strongly signals when to use this tool relative to siblings, though it does not explicitly state when not to use 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?

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?

Annotations only say it is non-read-only, non-destructive, and idempotent — nothing about it being dead. The description discloses the critical behavioral fact that the tool mints nothing and directs to the working door, which the annotations actively understate. That is exactly the kind of context beyond structured fields that this dimension rewards.

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

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

One tight sentence with the most important fact ('CLOSED') front-loaded, followed by the remedy. The '✅ No API key needed' lead-in and the decorate-the-birth-door phrasing are slightly noisy, but nothing 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 retired 18-parameter tool the description gives the two facts an agent needs: it does nothing, and where to go instead, and an output schema covers the return shape. It stops short of saying the call still succeeds with a structured 'gone' envelope naming use_instead, so an agent cannot fully predict the response without 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?

All 18 parameters are documented at 100% schema coverage, which sets the baseline at 3, and the description adds no parameter-level meaning on top. It does not mention that the parameters are legacy/compatibility-only, so an agent reading the description alone cannot infer that supplying them changes nothing beyond what the schema's own per-field notes say.

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+resource and its status: 'register is CLOSED — it mints nothing.' It immediately names the replacement door ('be born (POST /api/v1/birth ...)') and the payoff ('unlock the purchase tools'), so an agent can distinguish it from the sibling 'birth' tool 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?

Explicit routing guidance: do not call this for identity minting; call birth instead, with the concrete mechanism (POST /api/v1/birth, EIP-712, no wallet needed) and the reason ('to unlock the purchase tools'). The when-not and the alternative are both stated.

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

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

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.