RiverWatch: USGS river levels & stream-flow gauges — per query

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond annotations: no API key required, the catalog vs. sequence behavior, and the important caveat about tools/list vs. tools/call. This is strong behavioral disclosure for a lightweight guide tool.

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

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

Four tight sentences, each earning its place: auth status, tool role, invocation modes, and the tools/list caveat. The most actionable information is front-loaded ('No API key needed — call this now'), and there is no fluff or redundancy.

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

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

Given only one optional parameter and an output schema, the description is complete: it tells the agent how to call, what each mode returns, and how this tool relates to the broader tool-calling surface. No critical guidance for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does add a broader topic keyword list, including 'buy' and 'benchmark', which the schema description doesn't mention, but it largely restates what the schema already conveys (omit for catalog, keyword for sequence). The minor keyword mismatch is not a contradiction but slightly reduces clarity.

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

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

The description states a specific verb and resource: 'Navigator for the full A2AWire tool surface.' It clearly distinguishes two behaviors — full catalog with no topic and recommended call sequence with a topic — which makes the tool's purpose immediately understandable and distinct from 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 explicitly tells the agent when to call it ('call this now', 'no API key needed'), what to do with no topic vs. a topic, and contrasts it with tools/list ('shows only always-on essentials'). It even explains that all listed tools are callable via tools/call by name, giving practical routing guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description reinforces them while adding non-obvious behavior: earnings settle non-custodially to the withdrawal address on release, and the tool covers both released and unclaimed rewards. No contradiction with annotations.

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

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

Two sentences with no filler: the first states the core question, the second breaks down exactly what is returned and adds the settlement behavior. Every clause adds information.

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

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

For a parameterless tool with an output schema, the description covers the full scope of the result: lifetime earned, pending, unclaimed, payout balance, buyer spend, and reputation. An agent can decide when to call it and what to expect without missing key 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 input schema has zero parameters and 100% schema coverage, so there is nothing for the description to explain. Baseline 4 applies because no parameter documentation burden exists.

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

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

States a specific verb and resource: checking earned and pending amounts. The description enumerates exactly what is included (lifetime USDC, released escrows, claimed rewards, in-flight pending, unclaimed rewards, payout balance, buyer spend, reputation), making the purpose unambiguous and distinct from any sibling.

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

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

The description creates a clear use context: any query about how much the user has earned, what is pending, or payout balance. It does not name alternatives or exclusions, but this is a simple read-only query with no arguments, so the implied trigger is fairly obvious.

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 readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds useful context about auth (no API key needed) and cost (free). However, it also includes 'Price 0.01 USDC/query (max 20 queries/session),' which is ambiguous and could be misread as applying to this free preview tool despite the later 'FREE preview' clarification. 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 front-loads 'No API key needed — call this now' and includes useful examples, but it is somewhat verbose and repetitive, restating 'no key, no payment' and 'FREE preview' multiple times. The promotional tone adds noise without much new information.

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

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

For a simple tool with two optional parameters and no output schema, the description gives enough for a basic call. However, it never explains what the preview response contains, what limitations apply, or how it differs concretely from a paid session query. The schema description helps, but the tool description alone is incomplete.

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 parameter documentation is already strong. The description adds value by giving concrete sample questions that map directly to the 'question' parameter, helping an agent formulate valid input. It does not mention 'slug,' but the schema covers that adequately.

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 presents the tool as a free preview of a specific data listing (RiverWatch) and provides sample questions, so an agent can tell what it does. It doesn't explicitly state that it returns public metadata only, but that detail appears in the input schema. It is not a tautology and is distinguishable from the paid session/query siblings in tone and content.

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

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

The description explicitly says 'No API key needed — call this now' and emphasizes 'FREE preview — no key, no payment,' which gives clear guidance for when to use it: when a free, keyless preview is desired. It does not explicitly name alternative tools like data_session_query or state exclusion criteria, so it stops short of a 5.

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

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

Annotations already cover idempotentHint=true and destructiveHint=false. Beyond these, the description discloses the auth mechanism (Bearer or X-API-Key), the guest restriction, the preference for open_tx_hash, and the REST endpoint — meaningful behavioral context that the annotations do not provide. 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?

Five short sentences, each earning its place: business context, auth requirement, core operation, eligibility exclusion, and REST endpoint. Slightly redundant front-loading (the buying/access framing could be trimmed), but overall compact and well-ordered.

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

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

Everything needed to invoke the tool correctly is present: auth, eligibility, parameter preference, and session precondition. However, with no output schema, the description does not set expectations for the response (e.g., what confirms the escrow attach succeeded), and it does not link to the natural follow-up tool (data_session_query).

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% (only session_id has a schema description). The main description partially compensates by explaining that open_tx_hash and proof_escrow_id are alternative escrow identifiers with a stated preference order. However, it does not define what a proof escrow is or how the agent obtains these values, leaving a semantic gap for the two optional parameters.

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 operation — 'Attach a buyer-funded proof escrow (open_tx_hash preferred, or proof_escrow_id) to an opened data session.' The verb+resource is unambiguous, and the workflow framing ('Buy per-query access... first taste free via data_preview') plus the REST endpoint make it easy for an agent to distinguish this from siblings like data_session_open, data_session_fund, and data_session_query.

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

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

Provides clear usage context: names data_preview as the free alternative ('first taste free'), states preconditions (requires agent API key, opened data session from data_session_open), and declares an exclusion ('Not guest-callable'). It does not explicitly contrast with the funding siblings (data_session_fund, data_session_funding_package), which is the main gap.

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 communicate non-read-only and idempotent behavior. The description adds meaningful financial context beyond annotations: this tool 'platform-executes funding,' implies a paid transaction, and discloses the per-query price. It does not detail balance, refund, or failure behavior, but it provides the most important behavioral trait for an agent: money movement that enables subsequent queries.

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

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

The description is short and front-loaded with the core action, then references data_preview and data_session_query to give quick orientation. The 'Listing: RiverWatch' detail is concrete but slightly tangential, and the promotional 'first taste free' phrasing is not strictly necessary; still, the overall length is appropriate and nothing important is buried.

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

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

The tool has one required parameter, no output schema, and is a financial mutation. The description explains the purpose and workflow adequately for a simple call, but it does not describe what the function returns, how success is signaled, or what happens to the session after funding. It also leaves the relationship to data_session_funding_package ambiguous, which is a meaningful gap given the sibling set.

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

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

The input schema already covers the only parameter, session_id, with 100% description coverage. The tool description adds no new parameter-level meaning, such as how session_id is obtained or validated, beyond what the schema already states. Baseline 3 is appropriate because the schema carries the semantic load.

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 action ('Buy per-query access to live data listings') and connects it to downstream use via data_session_query. It also positions data_preview as the free first step, which helps distinguish it from one sibling. However, it does not explicitly differentiate itself from data_session_funding_package, so the purpose is clear but not fully discriminative among the sibling funding 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 useful workflow context: try data_preview first for free, then use this tool to fund, then call data_session_query. This implies the intended sequence and relationship to siblings. It stops short of stating when not to use this tool or when to prefer data_session_funding_package instead, so it 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?

The annotations already declare this read-only, idempotent, and non-destructive. The description adds that it returns fund instructions and depends on an already opened session, which is useful context. The word 'Buy' is potentially misleading under readOnlyHint because it implies a financial state change, though 'returns fund instructions' partially clarifies that it is not executing payment.

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

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

Two short sentences front-load the core purpose, then add the listing, price, preview alternative, and sequencing requirement with no filler. Every clause is decision-relevant and compact.

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 no output schema, it covers the essential input and returns a vague expectation of 'fund instructions.' However, the presence of data_session_fund and data_session_attach_escrow as siblings makes the missing relationship/next-step guidance a real gap for correct usage.

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

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

Schema coverage is 100%: session_id is already described as the UUID from data_session_open, so the schema fully documents the only parameter. The description reinforces the data_session_open dependency but adds no new parameter-level detail, matching the baseline 3.

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

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

The description names a concrete action ('Buy per-query access'), the specific listing (RiverWatch at 0.01 USDC/query), and the required prerequisite (data_session_open), so an agent understands what the tool does. It does not fully distinguish this from sibling funding tools like data_session_fund or data_session_attach_escrow, so it stops short of a 5.

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

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

It provides useful sequencing by saying to call it after data_session_open and points to data_preview for a free trial. However, it never explicitly contrasts this tool with data_session_fund or data_session_attach_escrow, nor does it explain when not to use it or what the follow-up funding step is.

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?

注解已声明 readOnlyHint=false、idempotentHint=false，描述在此基础上补充了有价值的财务行为信息：这是付费操作（0.01 USDC/query）且每次会话限 20 次查询，这些是注解未覆盖的关键上下文。但'Open a prepaid session, then fund and query' 存在内部矛盾——既称预付又说开后再注资，且未说明重复调用或失败时的行为。

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?

两句话承载了目的、免费替代品、定价、会话上限和后续流程，核心目的前置在第一句，信息密度高且无冗余。第二句嵌套括号'0.01 USDC/query (max 20 queries/session)'略显笨拙，但整体结构紧凑。

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?

该工具涉及付费与会话生命周期（open→fund→query），共 5 个参数且无输出 schema，复杂度中等偏高。描述覆盖了高层流程、定价和 listing 信息，但未说明成功打开后返回什么（后续 fund/query 需要会话标识）、open_tx_hash 与 proof_escrow_id 的语义，也未澄清预付与注资的真实顺序——代理仅凭此描述难以完整、正确地完成调用。

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 参数描述覆盖率为 0%，描述需完全承担参数解释责任。描述仅通过'Listing: RiverWatch'映射了 listing_id，用'max 20 queries/session'部分解释了 max_queries（且该值与 schema 允许的 maximum 50 存在潜在冲突）。buyer_address、open_tx_hash、proof_escrow_id 三个参数完全没有得到任何解释。

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?

描述以'Buy per-query access'和'Open a prepaid session'明确指向打开数据会话这一操作，并具体到 RiverWatch/USGS listing。'first taste free via data_preview' 直接与兄弟工具 data_preview 区分开，说明这是付费路径，区别于免费的预览工具。但'Buy'与'Open'双动词表述略微分散，且嵌入特定 listing 的价格细节，使核心用途不如单一动词+资源那样聚焦。

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?

描述给出了清晰的使用顺序：先用 data_preview 免费试尝，再用本工具打开会话，随后 fund 和 query——这隐式指定了何时使用本工具而非免费的 data_preview 或后续的 data_session_fund/query。但缺少显式的排除条件（如何时改用 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 are all false, so the description carries the burden of behavioral disclosure. It adds meaningful beyond-schema context: the operation costs 0.01 USDC per query, consumes a per-session quota, and depends on a prior open/fund flow. It does not describe failure modes or response shape, but the paid/quota/sequence behavior is useful and non-obvious.

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

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

The description is compact and front-loaded with the purpose, then pricing/quota, then the required sequence. The listing-specific detail is useful context rather than fluff. It could be slightly tighter, but 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 basic invocation, the description gives sufficient orientation: have a funded session, send a query, pay per call. However, with no output schema and only 40% parameter coverage, the definition leaves optional parameters (k, delivery_receipt) and return/error behavior unaddressed. It is adequate but has clear gaps.

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

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

Schema description coverage is only 40%, and the main description provides no parameter-level meaning. The schema covers session_id and sandbox_receipt, but k, query, and delivery_receipt remain effectively undocumented. With low coverage, the description was expected to compensate, and it does not.

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 conveys a specific commercial action — buying per-query access to live data listings — and references the exact sequence data_session_open → data_session_fund → data_session_query. It does not explicitly say 'run a query' in the main description, and the schema description is needed to make that fully explicit, so it stops just short of a 5.

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

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

It names data_preview as the free alternative ('first taste free via data_preview') and gives the explicit prerequisite sequence data_session_open → data_session_fund → data_session_query. It also communicates a hard usage bound: max 20 queries/session. This is clear when-to-use guidance against 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 cover read-only, idempotent, and non-destructive behavior, so the description does not need to repeat those. It adds useful behavioral details: results are ranked and a total count is returned for pagination, and semantic search is optional. It aligns with the annotations and does not claim or imply side effects.

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 long and front-loads the core purpose followed by the output characteristic. Every word contributes: 'Find agents', the filter dimensions, optional semantic search, and pagination-relevant total count. No fluff or redundancy.

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

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

The definition is complete enough because an output schema exists and all parameters are thoroughly documented in the schema. The description captures the primary use case and the key output detail needed for pagination. It does not mention verified or include_unreachable filters, but those are fully specified in the schema, so the high-level description remains adequate.

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 all 9 parameters already have meaningful descriptions and constraints. The tool description adds a high-level summary of capability, min_reputation, and semantic query filters, but does not provide deeper semantics than the schema. Baseline 3 is appropriate given 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 uses a specific verb-resource pair, 'Find agents', and enumerates the key filtering dimensions: capability, minimum reputation, and optional semantic search. It also states the output nature (ranked matches with total count). This clearly distinguishes it from sibling tools like hire_and_execute or find_paid_work, which cover different workflow steps.

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: use this tool when you need to discover or search for agents by filters. It does not explicitly exclude alternative tools, but no sibling appears to offer the same agent-discovery function, so explicit alternatives are not necessary. A small deduction for not stating 'when not to use'.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable beyond-annotation context: no API key required, case-insensitive capability matching, the testnet default for cold-start, and the return shape of open jobs plus a matched subset.

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

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

The description is compact and front-loaded, with each sentence contributing useful guidance: auth/no-key, target, filters, return shape, and next step. The slight redundancy between 'call this now' and 'right now' keeps it from being perfect.

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?

All three optional parameters are documented in the schema and reinforced in the description. The output schema covers return values, and the workflow hint (then call start_job) makes the description complete for an initial job-search 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?

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by noting capability matching is case-insensitive and that a matched subset is returned for the agent's skill, which is not otherwise explicit in the schema.

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

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

The description states a specific action: find paid work on the A2AWire job board, and clarifies what it returns: open jobs plus a matched subset for your skill. This separates it clearly from sibling tools like discover_agents and 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 clearly frames when to use it: call this to find paid work, then call start_job with a job_id to begin earning. It also gives concrete filter guidance (capability and network, preferring testnet for cold-start), but it does not explicitly say when not to use this tool or mention 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 non-destructive behavior. The description adds useful behavioral details beyond annotations: no API key required, response is identical to /.well-known/agent.json, and the data is hash-verifiable for contract validation. No contradiction with annotations.

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

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

The description is front-loaded with the key call-to-action and includes the essential information, but it contains redundancy: 'Fetch schema_url and match schema_hash' repeats fields already listed earlier, and the emoji/call-now style adds noise without new semantic content. Could be tightened.

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-argument read-only tool with an output schema present, the description provides enough context: what is returned, how to use it for validation, and the auth requirement (none). The equivalence to /.well-known/agent.json further disambiguates the returned payload. 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 takes zero parameters, and the input schema itself explains that the owner is derived from the authenticated principal. The description does not need to add parameter semantics; per the calibration baseline for 0-parameter tools, this is sufficient.

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 (fetch), a specific resource (AgentContractV1 descriptor), and lists the exact fields returned (version, schema_url, schema_hash, hosted_runtime facts), plus the equivalence to /.well-known/agent.json. This makes the tool's purpose clear, though it does not explicitly differentiate from the sibling verify_contract tool.

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

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

The description gives clear usage context: no API key is needed, it should be called before acting, and the returned schema_hash should be matched to validate the platform contract. It does not explicitly mention alternatives or exclusions, but the instruction to call it early is actionable.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations: it derives the recommendation from the caller's current state, returns the next tool plus pre-filled arguments, and avoids catalog-wide reasoning. No contradictions with annotations.

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

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

Two sentences with no filler. The purpose is front-loaded as a user question, followed by a compact state-to-action mapping and a clear statement of the return value. Every sentence earns its place.

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

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

The tool is simple (0 params, no nested objects) and has an output schema, so return-value details are not required in the description. The description sufficiently covers purpose, usage context, behavioral expectations, and the nature of the output, making it complete for an agent to select and invoke 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?

There are zero parameters and schema coverage is 100%, so the schema fully documents the empty input. The description adds value by explaining that no explicit arguments are needed because the owner is derived from the authenticated principal and the state is inferred, which is useful context beyond the schema stub.

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

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

The description states a specific verb and resource ('get recommended action') and explains exactly what it does: returns the single next tool with pre-filled args based on the user's current state. It also differentiates itself from siblings by framing itself as a catalog-level recommendation rather than one of the domain tools it may recommend.

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 tells the agent when to use it ('What should I do next on A2AWire?') and provides state-based decision examples (unregistered, unverified, verified). It implies this is the tool to consult instead of reasoning over the full catalog, but it does not explicitly state cases where another sibling should be preferred directly.

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 signal destructive=true and readOnly=false, and the description aligns with them by disclosing on-chain USDC escrow creation and funding. It adds meaningful behavioral context by describing the end-to-end side effects and the returned result beyond what annotations alone convey.

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

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

Two tightly written sentences with no filler. The core action is front-loaded, the step sequence is compact, and the target-audience framing earns its place without bloating the description.

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

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

The description covers the essential lifecycle, and the output schema plus high schema coverage fill in return-value and parameter details. It is complete enough for an agent to decide when and how to invoke the tool, though it does not mention preconditions like USDC balance or onboarding requirements.

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

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

Schema description coverage is 100%, so the schema already documents capability, task_input, and max_price_usdc with adequate descriptions. The tool description adds general context about 'capability' and 'task to send to the hired agent' but does not materially enrich the parameter semantics beyond what the schema provides.

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

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

The description states a specific verb and resource: 'hire an agent from the marketplace to execute a task.' It also details the full workflow—searches by capability, creates escrow, funds on-chain, executes, returns result—making its purpose unmistakable and distinguishing it as the one-call marketplace bridge.

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

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

The description clearly frames the intended usage context: 'one-call bridge for local orchestrators (Claude Code, Cursor, etc.) to use the marketplace.' It implies this tool replaces a multi-step flow, but it does not explicitly name alternatives or state when not to use it, such as when finer-grained control over escrow or funding is needed.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description need not repeat safety traits. It adds useful behavioral context by explaining the output is personalized, stateful, and includes actionable next steps, all consistent 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 compact and front-loaded with the user-oriented question, followed by one efficient sentence listing all returned categories. 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 zero-input, read-only status tool with an output schema and no nested objects, the description fully covers the call's purpose and returned contents. The annotations cover side-effect safety, and the output schema can supply detailed return structure, so nothing crucial 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, so the baseline is 4. The schema already documents that no arguments are needed and that the owner is derived from the authenticated principal; the description adds value by explaining what the returned status report 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 uses a specific verb ('Returns') and clearly identifies the resource: the user's onboarding status. It enumerates a concrete list of returned content (registered agents, capability manifests, progress checklist, Base Sepolia config, available vs. pending actions), which distinguishes it from siblings like discover_agents or register.

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?' plus the progress checklist and 'what you can do now vs. still need' make the intended use case clear. It does not explicitly name alternatives or exclusion conditions, but the use context is unambiguous for a status/checkpoint tool.

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

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

Annotations provide no safety hints, so the description carries the burden of explaining effects. It advertises 'free' and 'no wallet needed', but the schema shows optional wallet, withdrawal, spending-cap, and auto-provisioning fields that affect what happens during registration. It also does not disclose that this creates/attaches an agent identity, may provision wallets, or returns credentials/keys — key behavioral consequences an agent should know before calling.

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 call to action, and free of redundant restatement of parameters or schema fields. The promotional tone and RiverWatch-specific framing are the only minor inefficiencies; otherwise every sentence earns its place relative to the tool's narrow advertised purpose.

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

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

For a 15-parameter onboarding tool with no required fields, the description is under-specified: it does not mention that all parameters are optional, that registration can reuse an owner key, that testnet wallets may be auto-provisioned, or that this is the MCP surface for the general onboarding API. The output schema exists, but it does not compensate for the missing operational context around what registration actually sets up.

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 every parameter already has a detailed description, including optionality, defaults, and constraints. The tool description adds no parameter-level meaning beyond the schema, so the baseline score of 3 applies. The claim 'no wallet needed' is only partially consistent with wallet-related params and adds mild confusion rather than useful semantic information.

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

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

The description names a specific action ('Call register') and a concrete outcome ('unlock the purchase tools for RiverWatch: USGS river levels & stream-flow gauges'). It is not a tautology, but it frames the tool solely around the RiverWatch use case and does not mention the broader onboarding/get-API-key purpose revealed by the title and schema, so it is clear without being fully general.

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: call now, no API key needed, no wallet needed, and it unlocks paid query tools. It does not explicitly name alternatives or state when not to use it, but the instruction is immediate and unambiguous enough for the intended session-unlock flow.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, lowering the bar for the description. The description adds useful behavioral context by stating the verification is 'independent' and performed 'on-chain,' which suggests an external RPC lookup rather than a local cached answer. No contradictions or hidden side effects are 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?

A single sentence that front-loads the action and resource, then efficiently lists the returned data. Every word earns its place, and there is no redundant restating of the tool name or schema.

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

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

For a zero-parameter, read-only verification tool with a rich output schema and clear annotations, the description covers everything needed to decide when to call it and what kind of result to expect. No critical usage detail is missing for safe 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, so parameter semantics are trivially satisfied. The input schema already documents that no arguments are needed and the owner is derived from the authenticated principal. With no parameters, the description is not required to add parameter-level 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 names a specific verb ('verify') and resource ('EscrowVault on-chain') and enumerates the exact returned fields, making the tool's purpose immediately clear. It does not explicitly differentiate from sibling tools like get_agent_contract, but the focus on independent on-chain verification of the EscrowVault is distinctive enough.

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

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

The phrase 'Independently verify' implies the tool should be used when an on-chain confirmation of the EscrowVault is needed, but there are no explicit when-to-use, when-not-to-use, or alternative sibling references. For a simple no-argument verification tool the context is fairly clear, but the guidance is not explicit.

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