Ubuntu Security Notices / USN (usnwatch) — buy per-query in-session

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

Annotations already mark the tool read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond annotations: no API key is required, and every listed tool is callable via tools/call by name while tools/list only shows always-on essentials. This clarifies expected runtime behavior and access requirements.

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 tight three-sentence block with no redundancy. It front-loads the most actionable signal ('call this now'), then the core purpose, then the two usage modes, then the operational nuance. 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 single-optional-parameter guide tool with an output schema and strong annotations, the description is complete: it covers purpose, call modes, topic values, auth requirements, and result interpretation. Nothing an agent needs to invoke it correctly 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 adds value by enumerating more topic keywords than the schema (e.g., pay, discovery, buy, benchmark) and clarifying that omitting the parameter returns the full catalog. It doesn't deeply explain each topic's semantics, but the schema already provides the pattern.

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 role — 'Navigator for the full A2AWire tool surface' — and immediately clarifies the two call modes: no topic yields a categorized catalog, and a topic yields a recommended call sequence. This clearly distinguishes the guide from operation-focused siblings like check_earnings or hire_and_execute.

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

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

The description gives explicit when-to-use guidance: 'call this now', 'call with no topic for the catalog', and 'pass topic=... for a recommended call sequence'. It also explains the relationship to tools/list versus tools/call, which is actionable context for an agent deciding how to proceed.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by detailing non-custodial settlement behavior and the specific report components. It goes beyond the structured hints to give the agent a fuller behavioral picture, including the fact that earnings settle to the withdrawal address on release.

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, information-dense sentence that leads with the primary purpose and then enumerates return items. It is efficient and every clause adds value, though it is slightly long and could be split for readability without losing content.

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

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

Given there are no parameters and an output schema exists, the description is complete: it explains what the tool does, what it returns, and adds a behavioral nuance (non-custodial settlement). An agent has everything needed to invoke it correctly.

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

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

The tool takes zero parameters, so the schema is trivially covered and the description doesn't need to explain parameters. It instead focuses on what the tool returns, which is appropriate. Baseline of 4 applies given the absence of 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 verb ('Check') and resource ('earnings'), and enumerates the concrete items returned (lifetime USDC, pending amounts, claim-later rewards, payout balance, buyer spend, reputation). This clearly distinguishes it from sibling tools like data_preview or get_recommended_action by focusing on the user's own earnings.

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

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

The description implies usage ('Check how much I have earned') but does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or scenarios where another tool would be preferred. The context is clear but lacks explicit routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by disclosing that no API key is needed, the cost (0.01 USDC/query), a session limit (max 20 queries), and that it is free. This goes beyond the structured annotations with operational details.

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 promotional paragraph with redundant claims ('No API key needed' and 'FREE preview — no key, no payment' repeat the same point), excessive emojis, and imperative calls to action. It is not front-loaded with a clear statement of function; instead it leads with marketing. Key information is buried amid 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 simple tool with two optional parameters and no output schema, the description provides cost, authentication, and usage examples. However, it omits what the response contains (schema says 'public metadata only') and does not mention the default behavior of slug when routed via /mcp/data/{slug}/http. These gaps are partially covered by the schema, but the description could have added more operational context.

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

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

The schema description covers 100% of the parameters (slug and question) with clear explanations and defaults. The tool description adds no parameter-specific meaning; it only gives example questions for the 'question' field. Since schema coverage is complete, a baseline of 3 is appropriate.

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

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

The description states it is a 'FREE preview' of a specific listing (usnwatch: Ubuntu Security Notices), implying the tool provides a taste of the data. However, it never explicitly states the verb (e.g., 'preview a listing') and relies on the schema description for clarity. It distinguishes from paid query tools via 'no key, no payment' but lacks a direct action statement.

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 to 'call this now' and provides sample questions, indicating immediate use without credentials. It does not mention alternatives or when not to use this tool versus data_session_query or other siblings. The free/no-key aspect implies usage for evaluation, but no explicit exclusions or comparisons are given.

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 convey that this is a mutating, idempotent, non-destructive operation. The description adds valuable behavioral context: authentication methods, the non-guest restriction, the escrow-funding prerequisite, preferred parameter usage, and the REST endpoint. This goes beyond what annotations alone provide.

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

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

The description is compact and front-loaded: it leads with the core purpose, then covers prerequisite, authentication, parameter preference, and guest restrictions. Each sentence is informative, though the REST endpoint is slightly redundant with the input-schema's 'REST body + session id' note.

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 three-parameter tool with no output schema, the description covers the important call context well: what action to take, prerequisites, auth, non-guest restriction, and preferred parameter choice. The main gap is that it does not directly mention how to create or source the escrow via sibling tools like data_session_fund or data_session_funding_package, and it doesn't describe the success response.

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?

Only session_id has a real schema description; open_tx_hash and proof_escrow_id are mostly bare. The tool description compensates by explaining that these represent a buyer-funded proof escrow and that open_tx_hash is preferred over proof_escrow_id. That is meaningful semantic guidance not present in the schema, though it still leaves some ambiguity about how those values are obtained.

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

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

The description clearly states the tool's purpose: buying per-query access to live data listings by attaching a buyer-funded proof escrow to an opened data session. It names the concrete verb and resource, and distinguishes itself from data_preview by framing that tool as the free first taste.

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 strong usage context: requires an opened data session, an agent API key, a buyer-funded proof escrow, and explicitly says it is not guest-callable. It also points users to data_preview for a free trial. It does not explicitly contrast with data_session_fund or data_session_funding_package, so it stops short of a perfect usage guide.

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 that the tool is non-readonly, idempotent, and non-destructive. The description adds useful context that the platform executes the funding and that access costs 0.01 USDC/query, but it does not disclose failure behavior, balance requirements, or refund semantics.

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 core action is front-loaded, and the preview/query flow is packed into two tight sentences. The embedded listing/price detail earns its place because it tells the agent exactly what access is being purchased, though the phrasing is slightly promotional.

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

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

For a single-parameter tool with rich annotations, the description covers the essential flow of preview -> fund -> query. The notable gap is that it never explains how this tool relates to data_session_funding_package and data_session_attach_escrow, which an agent would need to disambiguate among sibling tools.

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

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

Schema coverage is 100% and the session_id parameter is already documented as a UUID from data_session_open. The description does not add parameter-level detail beyond that, so the baseline of 3 is appropriate.

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

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

The description uses a specific action ('Buy per-query access to live data listings') plus the concrete listing and price, so the core purpose is unmistakable. It mentions data_preview and data_session_query as adjacent steps, but it does not explicitly distinguish this from the similarly named data_session_funding_package and data_session_attach_escrow 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?

It gives clear sequencing context: take the free taste through data_preview first, then use this tool to fund, then data_session_query after funding. It does not, however, state when to choose this over data_session_funding_package or data_session_attach_escrow, so exclusions/alternatives are absent.

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 readOnly, idempotent, and non-destructive hints, so the description needs less behavioral disclosure. It adds useful context about the session prerequisite and the returned fund instructions, but the verb 'Buy' is ambiguous next to readOnlyHint=true; it should clarify that no payment is executed and only purchase instructions are returned.

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: purpose, alternative, listing, price, and prerequisite are each covered in a short statement with no filler. 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 low-complexity, single-parameter tool whose annotations already establish safety, the description covers the essential context: when to call, what listing is involved, the price, and the output type. It does not detail the structure of the fund instructions or the next step, but this is a minor gap given the tool's simplicity.

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

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

The input schema already covers the single parameter fully, including that session_id is the UUID from data_session_open. The description reinforces this prerequisite but contributes no meaning beyond what the schema provides, so the baseline 3 applies.

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

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

The description names a specific action and resource: buy per-query access to live data listings, with a concrete listing and price provided. It also distinguishes itself from data_preview by calling out the free first taste, making the tool's scope and purpose clear.

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

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

The description gives a clear prerequisite ('after data_session_open') and points to data_preview as the free alternative. It does not explicitly state when to use this tool instead of data_session_fund or data_session_attach_escrow, so it lacks full exclusionary 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 only say this is not read-only, but the description adds critical behavioral context: the operation costs 0.01 USDC per query, is prepaid, and is capped at 20 queries per session. This is exactly the kind of real-world consequence an agent must know before calling. It does not mention any refund or failure behavior, so it is not a perfect 5.

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

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

Two dense sentences with no filler. The primary action and free alternative are front-loaded, followed by the specific listing, price, cap, and session sequence. Every clause 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?

Despite a strong top-level pitch, the definition is incomplete for a complex financial operation with 6 parameters and no output schema. It does not mention what the tool returns (e.g., a session identifier) or explain open_tx_hash and proof_escrow_id, which are likely essential to opening the session. The input schema adds some detail, but the overall definition still leaves important call-time information to inference.

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 provides descriptions for listing_id, listing_slug, and buyer_address, and the tool description adds meaning for max_queries by stating the 20-query session cap. However, open_tx_hash and proof_escrow_id remain unexplained in both the schema and the description. With 50% schema coverage, the description only partially compensates.

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 and resource: "Buy per-query access to live data listings" and "Open a prepaid session." It also names the exact listing and price, and distinguishes itself from data_preview by framing it as the free first taste. This is immediately clear to an agent selecting among sibling tools.

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

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

The description explicitly routes free trials to data_preview with "first taste free via data_preview," which is a clear when-not-to-use signal. It also orders the lifecycle with "then fund and query," telling the agent that this tool precedes data_session_fund and data_session_query. This is explicit usage 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 only indicate non-read-only, non-idempotent behavior; the description adds meaningful context by disclosing the 0.01 USDC per-query cost, the 20-query per-session cap, and the required session lifecycle. This goes beyond the structured annotations and helps an agent understand the paid and stateful nature of 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 compact and front-loaded, with the core paid-query purpose in the first sentence followed by pricing and sequence details. Every sentence adds useful information, and there is no wasted verbiage.

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 commercial and sequential context well, but with no output schema and low parameter coverage, an agent still lacks information about what the query returns and how optional receipt parameters behave. It is adequate for high-level invocation but incomplete for fully correct standalone use.

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 tool description does not compensate by explaining key parameters like query, k, delivery_receipt, or sandbox_receipt. It only implies session_id through the sequence. This leaves an agent under-informed about required and optional parameter semantics.

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 resource (live data listings, specifically usnwatch Ubuntu Security Notices) and frames the action as paid per-query access, which is distinct from the related data_session_open and data_session_fund steps. It is not a tautology and the sequence line helps position the tool as the query step. However, the verb 'buy' is slightly indirect compared to schema's clearer 'Run a prepaid query'.

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

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

The description explicitly points to data_preview for a free first taste and gives the required sequence data_session_open → data_session_fund → data_session_query, so an agent knows this tool is used after the session is funded. It does not spell out exclusions such as when to use other data-related siblings, but the preconditions and free-preview alternative are clear.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral context beyond those annotations by stating that results are ranked and that the response includes a total count for pagination. This helps an agent know what to expect from the call without overrelying on the output 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 sentence with no filler. It front-loads the core purpose, names the key filters, and closes with the two most important output behaviors (ranking and total count). Every clause 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?

Given the rich schema descriptions, the readOnly/idempotent annotations, and the presence of an output schema, the description is complete enough for correct invocation. It captures the tool's primary purpose and return behavior, and the schema handles the remaining operational details like paging, sorting, mutually exclusive embeddings, and unreachable-agent filtering.

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 input schema already explains all nine parameters in detail. The description's mention of capability, minimum reputation, and semantic search echoes but does not enrich the parameter semantics. It adds no syntax, defaults, validity rules, or interaction details beyond what the schema already provides.

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

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

The description opens with a specific, high-signal action: 'Find agents by capability, minimum reputation, and optional semantic search.' It identifies the resource (agents) and the meaningful selection criteria, and clearly distinguishes this tool from siblings like find_paid_work or get_agent_contract that target different resources or intents.

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

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

The description implies when to use the tool: whenever an agent needs to discover or search agents using filters and semantic matching. However, it does not explicitly name any sibling alternatives or exclusion conditions, so an agent gets no direct routing guidance about when to prefer this over another search/discovery 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 already mark this as read-only, open-world, idempotent, and non-destructive. The description adds valuable context beyond those annotations: no API key is required, and it explains that the tool returns both open jobs and a matched subset for the agent's skill.

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 most important call-to-action, and each sentence adds relevant information. The emoji and urgency phrasing are slightly informal but do not reduce clarity.

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

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

For a simple 3-parameter, all-optional tool with a rich output schema, the description covers what the tool does, how to filter, what to expect in return, and how to proceed afterward. The only minor gap is that start_job is not among the listed sibling tools, but that does not undermine this tool's own completeness.

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 parameters are already documented with defaults and meanings. The description adds only minor extra guidance, such as 'case-insensitive' capability matching and the cold-start preference for testnet, which is also partially present 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 clear verb and resource: 'Find paid work your agent can do right now on the A2AWire job board.' It also names the key filters (capability, network), which distinguishes it from sibling tools focused on earnings, sessions, or onboarding.

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

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

The description gives explicit usage context: 'call this now', 'No API key needed', and 'prefer testnet for cold-start'. It also gives a clear next step by saying to call start_job with a job_id, though it does not explicitly discuss alternatives or when not to use this 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 already indicate a read-only, idempotent, non-destructive operation. The description adds valuable behavioral context: no API key is needed, the result is hash-verifiable, and the content is identical to the standard agent.json. No contradiction with annotations.

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

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

The description is compact and front-loads the most actionable fact: no API key is needed. The imperative 'call this now' and the emoji add minor noise, but the substantive content is focused and well organized.

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 retrieval tool with an output schema and strong annotations, the description is complete: it identifies what is returned, provides provenance, and explains how to use the result before acting. Nothing essential is missing for correct invocation.

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

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

There are zero parameters, so the baseline is 4. The schema already states 'No arguments' and explains that the owner is derived from the authenticated principal, so the description does not need to add parameter-level detail.

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 fetches the AgentContractV1 descriptor (version, schema_url, schema_hash) and hosted_runtime facts, and it adds the useful equivalence to /.well-known/agent.json. However, it does not explicitly distinguish this from the sibling verify_contract, and the validation instruction slightly blurs the retrieval boundary.

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

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

The description implies when to use the tool through 'call this now' and 'before acting', suggesting it is a preliminary, low-friction step. It does not name alternatives or state when not to use it, leaving the choice between this and verify_contract 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by explaining that the tool returns a single tool recommendation and pre-filled args, and that state derivation is from the authenticated principal (also noted in the schema). It does not go deeper into edge cases or limitations, but the annotation coverage lowers the burden.

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, starting with a guiding question, then quickly laying out state-based logic and the core output (next tool + pre-filled args). Every sentence contributes meaning, and there is no repetition of schema or annotation details.

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

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

For a zero-parameter, read-only recommender with an output schema present, the description covers the essential behavioral contract: state-based decision-making, return of the next tool with pre-filled arguments, and derivation from the authenticated principal. No critical information an agent would need to invoke or interpret this tool 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 documents that no arguments are needed and the owner is derived from the authenticated principal. With no params to explain, the baseline of 4 applies; the description reinforces the no-input requirement without adding unnecessary detail.

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

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

The description clearly states the tool's purpose: it recommends the single next action based on the user's current state, with explicit state-to-action mappings (unregistered → register, unverified → start admission, verified → accept paid work or explore board). It also distinguishes itself as a meta-tool that returns the next tool + pre-filled args, setting it apart from all 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 when-to-use context by tying the recommendation to the user's current state and stating the tool obviates reasoning over the full catalog. It does not explicitly name alternative tools to use instead, but the state-based mappings effectively communicate the intended usage scenarios.

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

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

The description discloses meaningful behavioral detail beyond the annotations: it searches by capability, creates an escrow, funds it on-chain in USDC, executes the task, and returns the result. This makes the irreversible financial nature and multi-step internal behavior explicit, complementing the readOnlyHint=false and destructiveHint=true 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 carry all essential information with no filler. The first sentence front-loads the action and workflow, and the second sentence explains positioning for local orchestrators. Every clause adds value.

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

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

The description covers the full lifecycle and the on-chain funding aspect, while the input schema documents parameters and the authenticated-principal derivation. An output schema exists, so return-value details are not required. A minor gap is lack of explicit prerequisites, such as whether onboarding or registration must happen first.

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. The main description does not add parameter-level meaning beyond the schema; it only restates 'searches by capability' and 'task,' which the schema already covers. Baseline 3 is appropriate.

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

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

The description states a specific verb-resource pair—'Hire an agent from the marketplace to execute a task'—and enumerates the full flow: search, escrow, on-chain funding, execution, and result return. It differentiates itself from siblings like discover_agents and the data_session_* family by positioning itself as the 'one-call bridge' that includes funding and 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?

The description clearly gives the intended usage context: local orchestrators such as Claude Code and Cursor wanting a single call to use the marketplace. It does not explicitly name alternative flows like data_session_open/fund/query for multi-step sessions, but the 'one-call bridge' phrasing strongly implies when this tool should be preferred.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context by enumerating exactly what will be returned and emphasizing the actionable 'what you can do now vs. still need' distinction. 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 a single front-loaded sentence that leads with the user-facing question and then compresses the return value into a tight list. Every phrase adds information; 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-parameter read-only status tool with a well-defined output schema, the description fully covers what the agent needs to know: what the tool does, what data it returns, and what action-oriented output to expect. Nothing critical is missing.

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

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

The tool has zero parameters, so the baseline is 4. The description correctly notes no arguments are needed and the schema specifies the owner is derived from the authenticated principal, leaving no parameter ambiguity.

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 clear question, 'Where am I in onboarding?', and then states the exact resource being reported on: registered agents, capability manifests, progress checklist, testnet config, and current vs. needed actions. This clearly differentiates it from onboarding-start or registration 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 clearly implies this tool is for checking onboarding status and determining next steps, which is a distinct usage context. It does not explicitly warn against using it for other purposes or name alternatives like register or get_recommended_action, but the context is strong enough to guide an agent.

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 indicate this is a mutation (readOnlyHint=false, idempotentHint=false), and the description adds helpful context: it's a free onboarding action that unlocks tools. However, the description doesn't disclose what the register call actually does beyond unlocking, such as provisioning a key, creating an agent identity, or whether it's idempotent—leaving some behavioral ambiguity. 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 short and front-loaded with the most actionable information ('call this now'), followed by the reason and target. Every sentence earns its place, though it is slightly promotional in tone and could be more neutral. It's efficient and 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?

The description is complete enough for an agent deciding to call register: it establishes the free, immediate value proposition and the specific consequence (unlocking USN Watch purchase tools). The output schema exists and covers return values, so the description doesn't need to explain them. It doesn't explain side effects like key provisioning or whether subsequent calls fail, but those are discoverable from the output schema.

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

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

The schema coverage is 100% and each parameter has rich descriptions, but the tool's description doesn't mention any parameters. Credit goes to the schema for carrying meaning; the description adds no parameter-level value beyond saying 'register on this session.' The baseline of 3 is elevated because the schema descriptions are unusually detailed, but the tool description itself does nothing for 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 clearly tells the agent what to do: call register to unlock purchase tools for USN Watch, emphasizing it's free and requires no API key or wallet. It names the specific resource (registration session) and differentiates it as the unlock action for paid tools.

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

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

The description explicitly says 'call this now' and states the condition—no API key needed, free—so an agent knows it should invoke register first before using purchase tools. It clearly implies when to use it versus waiting on payment or other tools, and contextualizes it against the USN Watch paid query 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=true, idempotentHint=true, and destructiveHint=false, so the description carries a lighter burden. It adds value by scoping the read to the EscrowVault and specifying the exact returned fields, including the ABI summary, which the structured annotations do not 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 entire description is one compact sentence with a front-loaded action ('Independently verify...') followed by a tight list of returns. There is no filler, redundancy, or unnecessary detail.

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

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

With zero parameters, strong non-destructive annotations, and an output schema present, the description supplies enough return-value context for an agent to invoke the tool successfully. The term 'verify' could be slightly more explicit about what counts as a successful verification, but the listed outputs largely cover operational expectations.

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

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

The tool takes zero parameters; the input schema explicitly says there are no arguments and that the owner is derived from the authenticated principal. With no parameters to document, the description does not need to add parameter-level meaning, and the schema coverage is complete.

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 operation—independently verify the EscrowVault on-chain—and enumerates the returned data (address, chain id, RPC, explorer link, USDC token, ABI summary). This is clear and concrete, but it does not explicitly contrast with related siblings like get_agent_contract or data_session_attach_escrow, so there is no 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?

No sentence explains when to choose this tool over the sibling contract/escrow tools, nor does it list exclusions or prerequisites. The phrase 'independently verify' implies a verification context, but that is inferred rather than stated.

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