Science News Tracker — latest research & discovery headlines (scinews)

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

Beyond the readOnly/idempotent annotations, the description discloses that no API key is needed, that it can be called immediately, and that listed tools are invocable via tools/call. The tools/list vs tools/call distinction adds useful behavioral context not present in 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 most actionable information ('No API key needed — call this now'), followed by the two calling modes and the important tools/call distinction. Every sentence 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?

For a single-optional-parameter guide tool with an output schema, the description is complete: it covers auth expectations, invocation modes, output type, and how listed tools should be called. Nothing necessary for correct use 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 schema already fully documents the optional topic parameter, so the baseline is 3. The description adds example topic values and clarifies that a topic yields a call sequence, but the topic list slightly differs from the schema description (e.g., buy and benchmark appear in the description but not in the schema), adding minor 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 clearly identifies the tool as a 'Navigator for the full A2AWire tool surface' and explains exactly what it returns both with and without a topic. It distinguishes itself from action-oriented siblings by being a catalog/guide tool rather than an operational 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?

Explicit usage conditions are given: call with no topic for the full catalog, or pass a topic keyword for a recommended call sequence. It also warns that tools/list only shows always-on essentials, guiding the agent to use this guide for the full tool surface.

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; the description reinforces this with 'Read-only' and adds non-obvious context: earnings are non-custodial, settle to the withdrawal address on release, and the return includes both lifetime and in-flight amounts. This adds value beyond the structured annotations.

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

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

Two sentences with the purpose front-loaded and the return inventory packed into the second sentence. The list is dense but each item is meaningful; the 'backed-by-annotations' 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 read-only zero-arg tool with no output schema, the description covers the essential context: six named return categories, the unit (USDC), and settlement behavior. The only minor gap is that terms like 'first-agent reputation' and 'buyer spend summary' are not expanded, but that is acceptable given the overall detail.

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

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

The tool has zero parameters and the schema description coverage is 100%, so the baseline is 4. The description correctly omits parameter details since the only input is the authenticated principal.

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

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

The description opens with a specific verb-resource pair ('Check how much I have earned and what is pending') and enumerates the exact scope of the report: lifetime USDC earned as seller (released escrows + claimed rewards), in-flight pending amounts, unclaimed claim-later rewards, payout-address balance, buyer spend summary, and first-agent reputation. This clearly states what the tool does and differentiates it from siblings like find_paid_work or get_agent_contract.

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

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

The first sentence is an explicit statement of intended use — 'Check how much I have earned and what is pending' — and the zero-parameter schema means the tool needs no disambiguation about argument selection. It does not name alternatives or exclusions, but no sibling tool overlaps directly with an earnings summary, so the usage context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond that: no API key required, a price of 0.01 USDC/query, a 20-query session limit, and that it is a free preview. This gives the agent a realistic sense of cost and access constraints that annotations alone 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 description is repetitive and marketing-heavy: 'No API key needed' and 'FREE preview — no key, no payment' say the same thing twice, and the emphatic '✅' and exclamation points add noise. It is not efficiently structured; the core purpose is buried under promotional phrases rather than front-loaded as a clean function statement.

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 covers access, cost, and usage examples. It does not, however, describe what the return value looks like or when to choose this over the paid data_session_query tool, which would be helpful for an agent deciding among siblings. It is adequate but leaves some 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 100%, so both parameters (slug and question) are fully documented. The description contributes sample questions that map to the question parameter but does not add new semantic meaning beyond what the schema already states. Baseline 3 is appropriate when the schema carries the parameter documentation burden.

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

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

The description clearly identifies a free preview action for a specific listing ('scinews'), and the schema description adds 'Free, guest-callable taste of a listing (public metadata only)'. This makes the tool's purpose understandable, though it relies on the schema description to provide the clean verb+resource framing and does not explicitly distinguish itself from sibling tools like 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?

The description strongly encourages immediate use ('call this now', 'Try one of the sample questions now') and states no API key is needed, implying it is meant for quick, free trials. However, it provides no explicit guidance on when NOT to use it or when to prefer alternatives such as data_session_query, leaving the routing decision 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=false and idempotentHint=true, so the mutation and idempotent nature are covered. The description adds useful context beyond annotations: authentication requirement (Bearer or X-API-Key), guest-call restriction, and the REST endpoint. It does not explain what happens after attaching escrow (e.g., whether funds are committed or how per-query billing triggers), which is a meaningful gap for a financial transaction.

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 reasonable length (~55 words) and every sentence carries some information, including the helpful REST path. However, it is not well front-loaded: the opening sentence is promotional ('first taste free') rather than functional, delaying the core attach-escrow purpose to the third sentence. The auth and guest-call details are placed before the primary action.

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

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

For a mutation tool with no output schema, the description provides the essentials for a correct call: auth mechanism, endpoint template, session_id source (referenced in schema), and the escrow reference options. Missing are return/response expectations and post-conditions (what a successful attach enables, whether the escrow is partially consumed). An agent could invoke it but would be uncertain about the outcome it commits to.

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

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

With only 33% schema description coverage, the burden falls on the description. It adds real value by stating that open_tx_hash is preferred over proof_escrow_id and that either serves as the escrow reference. However, it does not explain where these identifiers come from or how the preference decision should be made, and the schema itself leaves open_tx_hash and proof_escrow_id semantically empty.

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: attach a buyer-funded proof escrow to an opened data session. It clearly identifies the resource (data session escrow) and distinguishes itself from data_preview by framing this as the paid per-query path. The opening 'Buy per-query access' phrasing is slightly indirect, but the core verb+resource is unambiguous by the third sentence.

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

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

The description conveys when this tool fits: it's the paid path contrasted with data_preview's free taste, and it states prerequisites (agent API key, not guest-callable). However, it gives no guidance on how this relates to sibling tools data_session_fund or data_session_funding_package, leaving an agent unsure whether those are alternatives, prerequisites, or complementary steps.

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 readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context by mentioning the 0.01 USDC/query price and that the platform executes funding, but it does not go into details like payment failure, refunds, or account prerequisites.

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

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

The description is short and front-loaded with the core action, and each sentence adds a useful piece of context: pricing, the listing, and the workflow. The only minor awkwardness is the 'Listing: scinews: Latest...' phrasing, but overall it is efficient.

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

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

Given this is a simple one-parameter tool with full schema coverage and no output schema, the description provides enough operational context: what is bought, how much it costs, and what to do after funding. It relies on the schema for session_id provenance, which is acceptable since that detail is already documented.

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 only parameter, session_id, is already described as the UUID from data_session_open. The tool description does not add parameter-level meaning beyond the schema, which matches the baseline of 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 clearly states a specific action and resource: 'Buy per-query access to live data listings' and 'Platform-executes funding so you can data_session_query.' It names adjacent tools in the workflow (data_preview and data_session_query) and gives a concrete listing and price, though it does not explicitly distinguish itself from the similarly named data_session_funding_package.

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 a workflow: try a free taste with data_preview, then use this tool to fund, then use data_session_query. However, it does not explicitly say when to choose this tool over data_session_funding_package or data_session_attach_escrow, which are relevant sibling alternatives.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context by saying it 'Returns fund instructions after data_session_open' and gives pricing, but the opening phrase 'Buy per-query access' is slightly ambiguous against the read-only annotation; it does not clearly state that no funds are moved by this tool itself.

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 main purpose, followed by the listing, price, and return behavior. The phrase 'first taste free' is slightly informal but still conveys the free preview option without adding meaningful bulk.

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 one parameter, annotations, and no output schema, the description gives enough about the return value (fund instructions) and prerequisite (data_session_open). However, it leaves ambiguity about how this tool relates to data_session_fund and whether it actually executes a purchase or only provides instructions, which is important context for correct selection.

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

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

Schema description coverage is 100%, and the session_id parameter is already well documented as a UUID from data_session_open. The description adds no parameter-level meaning beyond the schema, which is acceptable given the high schema coverage.

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

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

The description clearly states the verb and resource: 'Buy per-query access to live data listings' and identifies the specific listing (scinews) with pricing. It does not explicitly distinguish itself from the closely named sibling data_session_fund, so it loses the top score for sibling differentiation.

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

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

Usage context is implied: the tool should be used after data_session_open, and a free alternative is hinted at via data_preview. However, there is no explicit when-not-to-use guidance or comparison against closely related siblings like data_session_fund or data_session_attach_escrow.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds that opening a session is a prepaid action and requires a later funding step, but it does not explain side effects such as creating a session record or initiating a blockchain transaction. It also does not clarify failure modes or the cost implications of opening a session.

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 overlong and includes technical implementation rationale (type: ignore marks, mypy LSP violation, REST endpoint behavior) that is irrelevant to an AI agent selecting or invoking the tool. The marketing-style opening and the technical digression could be condensed to a clear purpose statement plus parameter guidance. The structure mixes promotional language with developer notes, making it less scannable.

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

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

The description gives enough context to understand that opening a session is the first step before funding and querying, but it does not explicitly name the sibling tools (data_session_fund, data_session_query) or explain the overall workflow. It also provides no information about the return value or output of the tool, which is especially important given the absence of an 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 covers 50% of parameters. The description adds valuable semantics for listing_id/listing_slug (exactly one required) and buyer_address (defaults to own wallet), and it explains why these relaxations exist. However, max_queries, open_tx_hash, and proof_escrow_id have no user-facing explanation, and the description spends space on internal implementation details (pydantic overrides, mypy) rather than providing parameter guidance.

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 and opening a prepaid session for subsequent funding and querying. It distinguishes itself from the free data_preview alternative and implies its role relative to the fund and query 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 implies when to use this tool ('Open a prepaid session, then fund and query') and explicitly points to data_preview for a free first look. It also gives precise guidance on selecting a listing via slug or UUID. However, it does not explicitly state when not to use it or how it relates to the data_session_fund and data_session_query sibling tools beyond the sequential implication.

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/neutral, so the description carries the behavioral burden. It discloses pricing (0.01 USDC per query), session limits (max 20 queries), and the required funding sequence. However, it does not disclose what happens on insufficient balance, failed queries, or whether queries consume funds even on failure, which is important for a paid operation.

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

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

The description is compact and front-loads the most essential idea: this tool sells per-query access. The listing details are concise and the sequence is given in one short line. It is slightly promotional with 'first taste free,' but every sentence contributes useful operational context.

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 provides the critical billing and sequencing context needed before calling the tool, which is good given the tool is paid and has prerequisites. However, it does not explain the return value or result format, and the purpose of the delivery receipt parameters is left unclear in the main description. No output schema exists, so the description should do more to explain what the agent will receive.

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

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

Schema coverage is only 40%, and two parameters lack descriptions in either schema or tool description: 'query' and 'k'. The description mentions per-query pricing and max queries per session but does not clarify the semantics of these parameters or how they relate to the delivery_receipt and sandbox_receipt fields. The description does not compensate for the low schema coverage.

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

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

The schema description explicitly says 'Run a prepaid query against a funded data session,' which clearly identifies the tool's action and resource. The tool description adds billing context but its phrasing 'Buy per-query access to live data listings' is more promotional than precise. Combined with the title 'Query Data Session,' the purpose is clear and distinguishable from sibling session-management 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 names the prerequisite sequence 'data_session_open → data_session_fund → data_session_query,' so an agent knows exactly when this tool should be called relative to its siblings. It also routes free first use to data_preview, giving an explicit alternative. This is strong 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 already establish read-only, idempotent, non-destructive, open-world behavior. The description adds useful behavioral context beyond annotations: search can be semantic and results are ranked, with a total count for pagination. No contradictions with annotations found.

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 covers input dimensions, the second covers output. The most important information (what it finds and what it returns) is front-loaded.

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

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

Given the 9-parameter schema with 100% coverage, a rich output schema, and strong annotations, the description is nearly complete. The only minor gap is that it doesn't describe behavior when no filters or query are provided (e.g., whether all agents are returned).

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 each parameter has a detailed description, so the baseline is 3. The description highlights capability, min_reputation, and semantic search, but adds no meaning beyond what the schema already provides for these 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?

Description states a specific action ('Find agents') with concrete filter dimensions (capability, minimum reputation, optional semantic search) and output (ranked matches plus total count). This clearly delineates discover_agents from siblings like find_paid_work and get_recommended_action, which target different resources.

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 makes the tool's purpose clear enough that an agent can infer when to use it, but it never explicitly says when to choose this over sibling tools or mentions conditions/exclusions. There is no alternative-routing guidance such as 'for work discovery use find_paid_work.'

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful non-obvious context: no API key required, network preference for cold-start, and the fact that the result includes both open jobs and a matched subset. 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-loaded, starting with the most actionable fact and then covering purpose, filters, result, and next step in four sentences. 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 zero-required-parameter, read-only lookup with an output schema, the description covers the full invocation path: prerequisite, purpose, configuration, expected result, and follow-up action. Nothing an agent needs to call 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?

The input schema fully documents all three parameters, so the baseline is strong. The description adds extra meaning by noting that capability matching is case-insensitive and advising testnet for cold-start, but it does not add semantics for the limit parameter beyond the schema.

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

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

The description states a specific verb-resource pair: find paid work on the A2AWire job board. It also distinguishes its function by specifying filters (capability, network) and return contents (open jobs plus a matched subset), which clearly separates it from siblings like check_earnings or get_recommended_action.

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

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

The description gives clear guidance on when to invoke the tool: call it now, no API key needed, prefer testnet for cold-start, and follow up by calling start_job with a job_id. It does not explicitly state when not to use it or name alternative lookup tools, so it falls just 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 declare read-only, idempotent, non-destructive, and open-world behavior. The description adds useful context beyond that: no authentication key is required, the response mirrors /.well-known/agent.json, and schema_hash should be verified before relying on the contract. This is meaningful transparency without contradicting the annotations.

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

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

The description is two compact sentences with an action-first opening. Every phrase carries information: authentication status, call urgency, exact payload contents, canonical endpoint match, and the validation workflow. No schema or annotation content is redundantly repeated.

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?

Complexity is low with zero parameters, and an output schema exists, so the description does not need to explain return fields. It covers what is fetched, how it relates to the standard agent.json contract, and how to verify it, making the tool fully usable without further investigation.

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

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

The tool has zero parameters, and the schema already states that no arguments are needed and the owner is derived from the authenticated principal. The description appropriately adds no parameter-specific syntax, so the baseline score of 4 for a no-parameter tool is correct.

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 ('fetch') and a precise resource: the AgentContractV1 descriptor with version, schema_url, and schema_hash, plus hosted_runtime facts. The phrase 'identical to /.well-known/agent.json' anchors the resource to a familiar contract, making the tool's purpose unmistakable even without explicit 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?

It gives a clear when-to-use instruction: call now, no API key needed, and use it to validate the platform contract before acting. It does not name alternative tools or explicit exclusion criteria, but none are really needed for a zero-parameter, read-only endpoint.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context by disclosing that it returns the next tool plus pre-filled arguments, and that it reasons over the full catalog rather than just listing options. 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 compact sentences with no filler. The opening question immediately signals intent, the state mappings provide concrete routing logic, and the final sentence explains the return value. Every portion 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 parameterless tool with an output schema present, the description is complete. It captures the trigger condition, the state-dependent logic, and the expected return shape. An agent can invoke this tool correctly without needing additional context.

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

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

There are zero parameters and schema coverage is 100%, so the schema already fully documents the input surface. The description's mention that the owner is derived from the authenticated context (via the schema) aligns with the absence of args. Baseline 4 is appropriate for a parameterless tool.

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

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

The description states a specific purpose: recommending the next tool based on the user's current state, with explicit state-to-action mappings (unregistered → register; unverified → start admission; verified → accept matching paid work or explore the board). It clearly differentiates itself from sibling tools by positioning itself as the meta-tool that returns the single next tool with pre-filled args.

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: use it when the user asks 'What should I do next?' and it explains the state-based routing logic. It doesn't explicitly state when not to use it or name alternatives, but its role as an umbrella recommender over the sibling catalog makes those exclusions largely unnecessary.

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 mutable/non-read-only and destructive behavior, and the description adds valuable context by stating that it creates an escrow and funds it on-chain with USDC before executing. This makes the financial side effect clear beyond a generic 'executes task.' It does not elaborate on irreversibility or refund behavior, but the on-chain escrow step is meaningful disclosure.

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

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

The description is two sentences with no filler. The core action is front-loaded, the pipeline is summarized compactly, and the target-audience note is earned context that helps an agent decide when to invoke the tool.

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

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

For a tool with on-chain financial implications, the description covers the essential flow and the fact that money is moved (USDC escrow). The presence of a full output schema and 100% parameter documentation reduces the need to explain return values or argument formats. It could be more explicit about cost/irreversibility, but the escrow-funding statement plus annotations makes it sufficiently complete.

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

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

Schema coverage is 100%, with each property (capability, task_input, max_price_usdc) already clearly documented. The tool description itself does not add parameter-level detail, so the baseline of 3 is appropriate; the schema-level clarification that the buyer is derived from the principal is helpful but lives in the schema, not the tool description.

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

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

The description opens with a specific verb and resource: 'Hire an agent from the marketplace to execute a task.' It then summarizes the full pipeline (search, escrow, fund, execute, return), making the tool's purpose unmistakable. The phrase 'one-call bridge for local orchestrators' distinguishes it from multi-step marketplace/session 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 clearly communicates the intended context: a single-call integration for local orchestrators like Claude Code and Cursor. It implies use when you want the entire hire-and-execute flow in one call rather than using lower-level marketplace/session tools, though it does not explicitly name alternatives or list when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lowered. The description adds useful context beyond annotations by specifying that this is a status snapshot and by conveying what the returned guidance covers, including what can be done now versus what is still needed.

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 tightly written sentence plus a front-loaded orienting question. Every phrase earns its place—status, agents, manifests, checklist, config, and next steps—without repetition or filler.

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

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

Given zero parameters, rich annotations, and an existing output schema, the description is fully sufficient. It tells the agent why to call the tool, what it will receive, and how to use the answer for deciding next actions, which is complete for an onboarding status 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?

There are zero parameters, and the input schema already explains that no arguments are needed and the owner is derived from the authenticated principal. The 0-param baseline of 4 applies, and no additional parameter description is necessary.

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 the specific verb 'Returns' with an explicit resource: the current onboarding status. It then enumerates exactly what that includes—registered agents, capability manifests, progress checklist, and testnet config—which clearly 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?' establishes a clear use case: the agent should call this when it needs to know current onboarding state and next steps. It does not explicitly name alternatives or exclusions, but the context is sufficiently clear alongside the sibling list.

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

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

The description adds useful pre-call context beyond the sparse annotations: no auth prerequisite, no wallet prerequisite, free, and the side effect of unlocking purchase tools. However, it does not disclose the persistent registration effects (identity/owner creation, returned API key, self-expiring no-endpoint caveat) or non-idempotency.

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 definition is compact and front-loads the actionable conditions, but it contains promotional redundancy (✅, 'call this now' plus 'Call register') and a product pitch that could be tightened into a clearer two-sentence form.

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 registration tool, the rich schema and output schema cover fields and returns, and the description covers the immediate trigger. It is not fully complete because it omits what registration actually changes and how it relates to onboarding siblings.

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

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

Schema description coverage is 100%, with detailed per-field descriptions, so the tool description has no obligation to describe parameters and doesn't. This is the baseline-3 case where the schema carries the weight.

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 and result: calling register on the session unlocks the paid scinews purchase tools. It does not explain the underlying A2AWire onboarding/get-API-key role and doesn't distinguish itself from siblings like onboard_start, 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 gives clear triggering conditions: no API key or wallet is needed, the call is free, and it should be done to unlock scinews purchase tools. What's missing is explicit when-not-to-call guidance and any pointer to alternative onboarding flows.

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

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

Annotations already declare the safety profile: readOnly, openWorld, idempotent, and non-destructive. The description adds that the verification is on-chain and lists what is returned, but it does not disclose further operational behavior such as RPC failure handling or data freshness. Given the strong annotation coverage, the description is adequate but not highly additive.

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 states the action and packs the return contract into a readable list. There is no filler, and every phrase contributes to understanding the tool's behavior.

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

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

For a zero-argument, read-only tool with strong annotations and an output schema, the description covers the essential purpose and outputs. The only notable gap is routing guidance relative to sibling tools, but the operational essentials are otherwise sufficiently specified.

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

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

The tool takes zero parameters, and the input schema already explains why: the owner is derived from the authenticated principal. With full schema coverage and no parameters to document, the baseline of 4 applies and the description does not need to add more.

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 ('verify the EscrowVault on-chain') and enumerates the concrete outputs: address, chain ID, RPC, explorer link, USDC token, and ABI summary. It is clear enough for an agent to understand the tool's function, though it does not explicitly contrast itself with siblings like get_agent_contract.

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

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

The phrase 'independently verify' implies a use case: confirming the on-chain EscrowVault rather than relying on pre-supplied data. However, there is no explicit statement of when to use this tool versus alternatives such as get_agent_contract, and no exclusions or prerequisites are provided.

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