MCP Server Discovery — new model-context-protocol repos ($0.01/query)

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

Annotations already mark it read-only, idempotent, non-destructive, and open-world; the description adds beyond-annotation context by stating no API key is required and explaining the relationship to tools/call and tools/list. This gives the agent actionable system behavior without contradicting any annotation.

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 deliver the key facts up front: no API key, the navigator role, the two calling modes, and the system-level note about tools/call versus tools/list. There is no filler; every sentence contributes to correct invocation.

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

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

For a read-only guide with an output schema, the description covers all needed context: authentication, optional parameter behavior, topic namespace, and how the results relate to the broader tool-calling system. Nothing essential is missing for an agent to decide to invoke it.

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

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

The schema already covers the topic parameter at 100%, so the baseline is 3. The description adds value by enumerating many valid topic keywords and clarifying that omitting the parameter returns the full catalog, though its keyword list including buy and benchmark is not fully aligned with the schema's list.

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 tool as a Navigator for the full A2AWire tool surface and states concrete outputs: a categorized catalog with no topic or a recommended call sequence for a topic. This clearly distinguishes it from the domain sibling tools, which perform specific operations rather than mapping the tool surface.

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 explicit call conditions: no topic for the catalog, a topic for a recommended sequence. It also provides an alternative distinction, noting tools/list only shows always-on essentials while this guide enumerates every callable tool, so an agent knows when to prefer it for discovery.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond this by adding that earnings settle non-custodially to the withdrawal address on release, which is useful behavioral context about finality and custody. It also summarizes what categories of data are returned, helping set expectations for the call.

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 core purpose is front-loaded, and the second sentence efficiently packs the return categories plus a behavioral note. Every clause adds information an agent needs.

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, rich annotations, and an existing output schema, the description fully equips an agent to select and invoke the tool. It states what the tool does, what the result covers, that it is read-only, and how settlement works — nothing crucial is missing for a safe and correct call.

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

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

The tool has zero parameters, so there is no parameter semantics burden. The schema already explains that no arguments are needed and that the owner is derived from the authenticated principal; the description reinforces this by referring to 'my' and 'your withdrawal address' without introducing any parameter expectations.

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

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

The description opens with a specific verb and resource: 'Check how much I have earned and what is pending.' It then enumerates exactly what is returned — lifetime USDC, pending amounts, unclaimed rewards, payout balance, buyer spend, and reputation — which makes the tool's scope unmistakable and distinct from siblings like find_paid_work or get_recommended_action.

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

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

The description gives clear context for when the tool applies: any time the user asks about earned, pending, or unclaimed earnings. It does not explicitly name sibling alternatives or state when not to use it, but the purpose is specific enough that an agent can route the call correctly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: no API key required, no payment required, a 20-queries-per-session limit, and the fact that it is a free preview. The 'Price 0.01 USDC/query' line is somewhat ambiguous against 'FREE preview,' but it does not contradict the annotations.

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

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

The description is padded with marketing language, emojis, repeated 'no key/no payment' statements, and a direct call-to-action ('Try one of the sample questions now'). It front-loads the key message but is not tight or information-dense. Several sentences could be removed without losing functional guidance.

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

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

For a simple, read-only preview tool with no output schema, the description covers access, cost, and usage examples. However, it does not clearly state what the tool returns, and the combined 'Price 0.01 USDC/query' with 'FREE preview' creates ambiguity. The schema's mention of 'public metadata only' helps, but the main description leaves the response semantics under-specified.

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 fully describes both parameters, so baseline is 3. The description contributes sample questions that illustrate the 'question' parameter's intent, but it does not add meaningful guidance about the 'slug' parameter or how to choose a different listing. It adds some value but does not go beyond the schema meaningfully.

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 free preview of a data listing and even gives sample questions to ask. It implies a read-only preview action, though it never explicitly states 'returns public metadata' in the main description. The 'FREE preview' phrasing helps distinguish it from paid data-session tools, but the distinction is implicit rather than named.

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 direct usage context: no API key is needed, it is free, and the user should try sample questions now. This strongly signals when to call the tool. However, it does not explicitly mention alternatives like data_session_query or state when NOT to use this tool, so it stops short of full routing guidance.

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

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

The annotations already capture idempotency and non-destructive mutation. The description adds useful behavioral context beyond that: authentication requirements, the guest-call restriction, and the preference for open_tx_hash over proof_escrow_id. It does not describe failure modes or side effects in detail, but it does not contradict the annotations.

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

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

The description is compact and front-loaded: it states the purpose, the free alternative, auth requirements, the action, and the REST endpoint in just four sentences. There is no filler or redundant restatement of the tool name.

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 three-parameter mutation with no output schema, the description supplies the essential invocation context: the opened-session precondition, auth needs, endpoint, and parameter preference. It could still mention what a successful response looks like or how errors surface, but an agent has enough information to attempt the call correctly.

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

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

Schema description coverage is only 33% since only session_id has a meaningful schema description. The tool description adds that open_tx_hash is preferred and that both parameters relate to a buyer-funded proof escrow, which is helpful. However, it does not explain what an open_tx_hash is, where to obtain these values, or how the two escrow identifiers differ operationally, so it only partially compensates for the low 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 names a specific action—attach a buyer-funded proof escrow—and a specific target: an opened data session. It also gives the broader purpose (buy per-query access to live data listings). However, it does not explicitly distinguish itself from sibling funding tools like data_session_fund or data_session_funding_package, so it stops 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 provides clear preconditions: requires an agent API key (Bearer or X-API-Key), is not guest-callable, and must target an opened data session. It also points first-time users to data_preview as a free alternative. It does not, though, spell out when to use this tool versus the other data-session funding siblings.

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 (readOnlyHint=false), idempotency, and non-destructiveness. The description adds some context—'platform-executes funding' and per-query pricing—but does not go deeper into side effects, such as what happens if the same session is funded twice. There is no contradiction with the annotations.

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

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

The description is short, front-loaded with the action, and includes a useful pointer to the free preview alternative. The listing-specific detail about ghmcp and the 0.01 USDC/query pricing is concrete but somewhat narrow for a generic funding tool; still, the overall structure is tight 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 simple one-parameter tool, the description plus annotations provide enough context to invoke it correctly: it explains what the tool does, how it relates to preview and query, and the session_id schema covers the only input. It does not describe the return value, but no output schema exists and the tool's success condition is fairly clear from the funding-to-query flow.

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%: session_id is fully documented as the UUID of a data session opened via data_session_open. The description adds functional context but does not need to repeat parameter details since the schema already covers them. This matches the baseline for high 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: 'Buy per-query access to live data listings' and 'Platform-executes funding so you can data_session_query.' It clearly identifies the resource as a data session and ties into the preview/query workflow. It does not, however, explicitly distinguish itself from data_session_funding_package or data_session_attach_escrow, which appear as siblings.

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 sequence guidance: first taste free via data_preview, then fund the session, then use data_session_query. This is useful when-to-use context relative to two sibling tools. It does not explicitly say when not to use this tool or when to prefer data_session_funding_package or data_session_attach_escrow.

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, so the safety profile is covered. The description adds that the tool returns instructions rather than executing a payment, and includes listing specifics. However, the verb 'Buy' may imply a state-changing purchase unless read together with 'Returns fund instructions', creating ambiguity that a clearer description would resolve.

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, each serving a purpose: the value proposition, the specific listing/price, and the postcondition/output. The most important use context is front-loaded.

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

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

For a one-parameter read-only tool, the description is mostly sufficient, but it returns only 'fund instructions' without specifying the instruction format or the next step (e.g., data_session_fund). Since there is no output schema, this vagueness is a gap.

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

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

Schema description covers the single session_id parameter at 100%, explaining it is a UUID from data_session_open. The tool description reinforces the dependency on an opened session but does not add new parameter-level meaning beyond the schema.

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

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

States a clear action ('Buy per-query access to live data listings') and a concrete output ('Returns fund instructions'), and references related workflow tools (data_preview, data_session_open). However, it does not differentiate from sibling data_session_fund/attach_escrow, so an agent could confuse which purchase-related step this is.

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

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

Gives an implicit workflow: try data_preview for free, open a data session, then call this for fund instructions. It does not explicitly state when NOT to use this tool or how it differs from data_session_fund / data_session_attach_escrow, leaving the alternative selection to inference.

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

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

The annotations only provide sparse hints (readOnlyHint=false, idempotentHint=false), so the description carries the burden. It discloses that this is a paid operation with a concrete price (0.01 USDC/query), a session cap (max 20 queries/session), and a multi-step flow. It does not clarify whether a blockchain transaction is required or what happens if a session already 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 three short, purposeful sentences: purpose, listing/pricing details, and workflow. It is front-loaded with the most important information and contains no filler.

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

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

For a paid, stateful opening operation with no output schema, the description omits what the tool returns (e.g., a session ID needed for subsequent fund/query calls) and does not explain the optional transaction/escrow fields. The basic invocation path is clear, but these missing details prevent full completion of the call loop.

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 0%, so the description must compensate. It gives one listing example ('ghmcp') and implies a query cap, but buyer_address, open_tx_hash, and proof_escrow_id are not explained at all. The 'ghmcp' value also does not obviously satisfy the schema's uuid format, and the stated 20-query cap does not align with the schema maximum of 50.

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

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

The description names a specific action ('Open a prepaid session') and a specific paid resource ('per-query access to live data listings'). It explicitly contrasts itself with data_preview and distinguishes the opening step from the later 'fund and query' steps, so an agent can tell it apart from sibling session/query tools.

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

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

It gives clear context: use data_preview for a free first look, otherwise start paid access by opening a session; then fund and query. The workflow sequence is clear, but the exact sibling tools (data_session_fund, data_session_query) are only implied by verbs rather than named as explicit 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?

With all annotations false (no read-only, idempotency, or safety hints), the description carries the disclosure burden. It adds genuinely useful behavioral context: the 0.01 USDC per-query cost and the 20-queries/session cap, which signal that this is a fund-consuming, non-idempotent operation. However, it omits failure/refund behavior and the receipt-signing mechanics tied to sandbox_receipt and delivery_receipt, which matter for a paid call.

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 tight sentences with no filler: the core idea is front-loaded, the listing specifics (ghmcp, price, cap) occupy one sentence, and the workflow sequence another. The only structural weakness is that the 'Buy' framing in sentence one is slightly misleading, so the opening is not as accurate as it could be.

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 paid, non-idempotent tool in a three-step flow with five parameters and no output schema, the description covers the workflow position and cost economics well. But it leaves significant gaps: the meaning of k, the delivery_receipt flow, and any sense of what the query returns or what happens on failure. It is adequate for navigating the sequence but incomplete for invoking the tool correctly with all parameters.

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

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

Schema description coverage is only 40%, below the 50% threshold, so the description must compensate for the undocumented k, query, and delivery_receipt parameters — it does not. The description is entirely about workflow, pricing, and the listing; it adds nothing about what any of the five parameters mean, leaving the agent dependent on a sparse 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 positions the tool via the sequence 'data_session_open → data_session_fund → data_session_query' and references the data_preview sibling, so an agent can roughly place it. However, the opening verb 'Buy per-query access' mischaracterizes the operation — the schema's own description says 'Run a prepaid query against a funded data session,' and purchasing is actually data_session_fund's role. The core action (running a query against a session) is implied by the sequence and name but never stated plainly.

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 explicit three-step sequence tells the agent that this is the final step, to be used only after data_session_open and data_session_fund. The phrase 'first taste free via data_preview' additionally routes the agent to the free alternative before paying. It lacks an explicit 'do not call before funding' exclusion, but the ordered workflow makes that condition strongly inferable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description does not need to repeat those traits. It adds useful output context by noting 'ranked matches plus the total count for pagination,' but it does not disclose behavioral nuances like query_embedding overriding sort_by or the default exclusion of unreachable agents, which are left to 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?

The description is a single focused sentence that front-loads the core purpose and adds the output summary. There is no filler or repetition; every phrase contributes to understanding what the tool does and what it 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?

Given the rich input schema, existing output schema, and comprehensive annotations, the description does not need to explain return values or parameter details. It captures the essential purpose and output shape well enough for a search tool. The main gap is the absence of usage routing relative to sibling tools, but that is already penalized under usage guidelines.

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

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

Schema description coverage is 100%, with all 9 parameters already documented meaningfully in the input schema. The description mentions capability, minimum reputation, and semantic search, but this only echoes the schema and adds no new semantic information. The baseline of 3 applies because the schema carries the parameter documentation burden.

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

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

The description clearly states the action ('Find agents') and the key filtering dimensions (capability, minimum reputation, optional semantic search), making the tool's purpose obvious. It also mentions the pagination-friendly output, which adds clarity. However, it does not distinguish this tool from sibling discovery-related tools such as find_paid_work or get_recommended_action.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. The filtering criteria imply general use cases, but the agent is left to infer when discover_agents is the right choice among the sibling tools.

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

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

Annotations already mark it read-only, idempotent, open-world, and non-destructive; the description adds non-obvious context: no API key required, returns a matched subset, and routes the next action to start_job. 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?

Mostly economical and front-loaded, leading with 'No API key needed — call this now' and then giving filtering and output behavior. Slight redundancy between 'call this now' and 'right now' is minor and does not hurt clarity.

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

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

Complete for a list/search tool with zero required parameters, full schema coverage, an output schema, and annotations covering safety. The only possible gap is that start_job is referenced but not listed among siblings, though this does not impair using find_paid_work 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?

All three parameters are fully described in the schema, and the description adds practical meaning—capability matching is case-insensitive, and testnet is preferred for cold-start. It also frames the response as both open jobs and a matched subset, which helps interpret the capability 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?

States a specific action (find) and resource (paid work on the A2AWire job board), and clarifies the output as open jobs plus a matched subset. It is clearly distinguished from sibling tools by scope—searching job opportunities—rather than agent discovery or execution.

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?

Provides clear context: no API key needed, call now, filter by capability and network, prefer testnet for cold-start. It does not explicitly name alternatives or exclusion conditions, but the context is strong enough to guide selection for finding paid work.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive, and the description adds real behavioral context: no auth required, exact source of truth (/.well-known/agent.json), hash-verifiability, and a validation workflow. No contradiction with annotations; remaining details such as failure modes are not disclosed, but the output schema covers return shape.

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 with important information front-loaded ('No API key needed — call this now'). The final sentence adds a useful validation workflow rather than inflating length, so 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 no-parameter read-only fetch with a rich annotation set and an output schema, the description is complete: it states when to call, that no auth is required, what fields are returned, and how the result should be used. Nothing needed for correct invocation is missing.

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

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

There are zero parameters and schema coverage is 100%, so the baseline is 4; the input schema already states that no arguments are needed and the owner is derived from the authenticated principal. The description adds no parameter-specific detail, which is acceptable because there is nothing to document.

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 concrete verb ('Fetch') and concrete resource ('hash-verifiable AgentContractV1 descriptor ... and hosted_runtime facts'), and further anchors it as identical to /.well-known/agent.json. It does not explicitly contrast with siblings like verify_contract or discover_agents, so it misses the top tier for 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 clear situational context: no API key is needed, this should be called now, and the contract should be validated before acting. It does not state when not to use the tool or name alternatives, but the 'call this now / before acting' framing is enough to indicate timing and precedence.

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 useful behavioral detail beyond the annotations: it reveals the state-dependent recommendation logic and that the return value is a single next tool plus pre-filled args. This is consistent with the readOnly, idempotent, and non-destructive annotations, so there is no 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?

The description is two sentences with no fluff. It opens with the user-facing question, then immediately provides the state mapping and return value, making it easy for an agent to absorb quickly.

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

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

For a zero-argument tool with an output schema, annotations, and a clear description, the information is complete enough to call and interpret. The state-to-action mapping and return format are both covered, and no critical operational 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?

The tool has zero parameters and the schema already states that no arguments are needed, with the owner derived from the authenticated principal. The description does not need to explain parameter meanings, so the baseline 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 clearly states the tool returns a single recommended next action with pre-filled arguments, tied to the user's current state on A2AWire. It distinguishes itself from general sibling tools by specifying the output format and state-based mapping (unregistered, unverified, verified).

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

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

The description gives clear context on when to use this tool: when the user needs a next-step recommendation and wants to avoid reasoning over the full catalog. It does not explicitly name alternative tools or provide when-not-to-use conditions, so it stops short of a full 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 declare destructiveHint=true and idempotentHint=false, and the description adds meaningful behavioral detail: it creates escrow, funds it on-chain in USDC, executes the task, and returns a result. It does not explicitly warn about the irreversibility of the on-chain funding, but the annotation and step list provide a reasonably clear picture.

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 action and pipeline, the second identifies the intended audience and positioning. Every sentence earns its place, and key information is front-loaded.

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

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

For a complex tool involving escrow and on-chain USDC funding, the description covers the high-level flow, return of results, and target users. The output schema and input schema fill in parameter and return details, but the description could add a caution about the financial and destructive nature of the 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 input schema already documents all three parameters with descriptions, including the max_price_usdc default and format. The tool description adds only high-level context that it 'searches by capability' and funds on-chain, which maps to capability and max_price_usdc but does not significantly expand on the schema's parameter documentation.

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

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

The description uses a specific verb and resource: 'Hire an agent from the marketplace to execute a task,' and then enumerates the full pipeline (search, escrow, funding, execution, result). It is clearly distinct from the multi-step data_session siblings by positioning itself as 'the one-call bridge,' though it does not name sibling alternatives 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 clear usage context: this is the one-call entry point for local orchestrators like Claude Code or Cursor to use the marketplace. It implies a contrast with multi-step flows and alternative tools but does not state when not to use it or explicitly name alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is well covered. The description adds useful behavioral context by specifying what the status report includes, including a progress checklist and exactly what the user can do now versus later, which is more than 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?

The description is a single, front-loaded sentence that leads with the purpose and packs the key output categories into a compact list. Every phrase earns its place, and there is no redundant or vague filler.

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

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

Given the tool's simple zero-parameter shape, rich annotations, and existing output schema, the description fully covers what the agent needs: what the tool returns, why it matters, and how it frames next steps. There are no material gaps that would prevent correct selection or invocation.

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

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

The tool has zero parameters, and the input schema already states that no arguments are needed and the owner is derived from the authenticated principal. With no parameters to document, the description has no additional semantic burden 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 states a specific verb ('Returns') and a well-defined resource (onboarding status), then enumerates the exact contents: registered agents, capability manifests, progress checklist, Base Sepolia config, and current vs. remaining actions. It clearly distinguishes itself from siblings like discover_agents or get_recommended_action by framing the tool as a consolidated status snapshot rather than a single-purpose lookup.

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

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

The opening question 'Where am I in onboarding?' provides a clear contextual trigger for when to use this tool. It does not explicitly name sibling alternatives or state when not to use them, but its scope is clear enough that an agent can infer this is the go-to for overall onboarding status.

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

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

Annotations only indicate that the call is not read-only, not idempotent, and not destructive, so the description carries the burden of side-effect disclosure. It adds that no API key or wallet is required, but it never mentions that registration provisions an owner/agent identity, may auto-provision a testnet wallet, or returns an API key once. There is no contradiction with annotations, but most behavioral consequences are left to schema inference.

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

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

The description is compact and front-loaded with decision-relevant facts about cost and prerequisites. However, the promotional style ('✅', 'call this now') replaces operational substance, so the conciseness is achieved partly by omitting important context rather than by dense 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?

The schema and output schema carry most operational detail, and the description supplies useful context about when to call and what it costs. What is missing is a plain statement of registration's side effects and what credentials or identity are created—important for a mutating, non-idempotent 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 covers 100% of the 15 parameters with rich descriptions, so the baseline of 3 applies. The top-level description adds no parameter-specific meaning and does not even mention that an empty object is a valid registration, so no extra credit is warranted.

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 the action ('Call register on this session') and its intended effect ('unlock the purchase tools for ghmcp'), so it is more specific than a tautology. However, it never states the underlying operation—registering/onboarding an agent and obtaining an API key—which the agent must infer from the title annotation and schema name.

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 is explicit about when to call: it is positioned as the zero-prerequisite first step ('No API key needed — call this now', 'Free — no wallet needed') before using paid purchase tools. It does not mention exclusions or alternatives such as onboard_start, so it misses the top score.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful context by stating the verification is 'independently' performed on-chain and describing what the returned verification payload contains, going beyond the structured annotation fields 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 a single, front-loaded sentence that conveys the purpose and key output contents without any filler. Every part adds value, and the structure makes the tool's behavior immediately understandable.

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 a full output schema and complete annotation coverage, the description provides all essential context. It explains the verification scope and the categories of returned information, leaving no obvious operational gaps.

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

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

The tool has zero parameters, and the schema description already states that no arguments are needed because the owner is derived from the authenticated principal. The description adds no parameter details because none are required, which matches the baseline for a parameterless 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 ('verify'), a specific resource ('the EscrowVault on-chain'), and enumerates the returned data (address, chain id, RPC, explorer link, USDC token, ABI summary). It is clear and informative, though it does not explicitly differentiate itself 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?

The phrase 'Independently verify' implies when to use the tool—when an on-chain verification of the EscrowVault is needed—but no alternatives or exclusion conditions are mentioned. Usage context is implied rather than explicitly stated.

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