intelligence

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

Annotations already declare readOnlyHint and openWorldHint, yet the description adds the crucial non-obvious caveat that the sample is illustrative and must not be treated as current market evidence, plus the cost implication ('before paying'). This is exactly the semantic context annotations cannot convey.

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

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

Two sentences, front-loaded with the action and immediately followed by the interpretation caveat. No filler and no repetition of schema or annotation 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?

There is no output schema, so the description must characterize the response, and it does so ('response shape and evidence style'). For a one-parameter read tool with full annotation coverage, 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?

With a single parameter at 100% schema description coverage, the schema already documents serviceId fully. The description adds no format, sourcing, or lookup guidance for the id, 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?

States a specific verb and resource (fetch a free illustrative sample of a service's output) and clarifies the scope of what is returned. It is immediately distinguishable in kind from the sibling tools, but it never names or contrasts them explicitly, so it falls short of the top band.

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

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

Gives a clear condition for use - inspect response shape and evidence style before paying - which is genuine routing guidance. It does not name an alternative tool or a when-not-to-use case beyond the implicit warning about treating the sample as market evidence.

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 openWorldHint=true, so the description's extra disclosure is what matters. It adds that the tool issues terms 'exactly as the paid endpoint' does, that settlement happens over a separate HTTP endpoint, and that no MCP client holds a wallet for signing. These are useful behavioral traits beyond the annotations, though it doesn't mention potential rate limits or error conditions, which are minor for a read-only tool.

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

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

Three sentences, each earning its place: the first states function and output, the second gives a concrete use case, the third clarifies boundaries and a key limitation. It is front-loaded with the core purpose and contains zero fluff or repetition.

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, read-only tool with no output schema, the description is remarkably complete. It covers what is returned, when to use it, what it doesn't do, and the settlement URL in the response. It doesn't define 'x402' or list error conditions, but those are optional for a tool this simple. A 4 reflects the high coverage without penalizing for non-essential omissions.

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

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

Schema coverage is 100%, so the parameter description already exists. The description's mention of 'service's report' slightly clarifies that serviceId refers to the service owning the report, but it doesn't add meaning beyond what the schema provides. Baseline 3 applies because the schema carries the parameter semantics fully.

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 ('read') and resource ('live x402 payment terms for a service's report'), enumerates exactly what is returned (price, one offer per settlement rail), and notes it matches the paid endpoint. This clearly distinguishes it from sibling tools like edge_get_free_sample or edge_get_service – an agent knows its function without opening the schema.

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

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

The description gives an explicit when-to-use: 'Use this to check a report's cost against your own spend policy before committing.' It also provides a clear when-not-to-use: settlement is not done through this tool and requires the plain HTTP endpoint named in the response. This covers both usage context and an alternative pathway, exceeding the baseline.

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, so the safety profile is covered. The description adds useful behavioral context beyond that: it specifies the exact contents of the returned record and the notable behavior that 'the top result is the exact id match,' which helps agents interpret potentially ranked results.

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

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

Three sentences with no filler: the first states purpose and return contents, the second gives the critical usage instruction, and the third clarifies result ordering. Every sentence earns its place and the most important information is front-loaded.

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

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

For a simple read-only lookup with one required parameter, the description covers what is returned, when to call it, and how to interpret the top result. It does not mention error behavior for an unknown serviceId, and there is no output schema, but the listed return fields largely compensate for that gap.

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

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

Schema description coverage is 100%, and the serviceId parameter is already documented as coming from edge_search_services or a bundle's sample.serviceId. The description only says 'by its id,' adding no semantic information beyond the schema, so the baseline score 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 a specific verb and resource: 'Look up one service by its id and return its full public record.' It enumerates the exact returned fields and explicitly distinguishes this single-record lookup from a search operation, making the tool's purpose immediately clear and separable from siblings like edge_search_services.

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 before purchasing so the price and freshness are known rather than assumed.' It does not name alternative tools or state when not to use it, but the pre-purchase instruction plus the id-based lookup clearly implies when this tool is appropriate.

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 openWorldHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the response shape (a count per family) and the intended workflow (browsing, pre-purchase coverage checks), which the 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?

Two sentences, no filler. The what (families with counts) is front-loaded and the when-to-use follows immediately.

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 listing tool with no output schema, the description covers both what is returned (families plus counts) and when it is worth calling. Nothing essential is missing, though naming the alternative tool explicitly would close the last gap.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a 0-param tool is 4. Schema coverage is also 100%, so no compensatory detail is required.

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

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

States a specific verb and resource ('List the families the catalogue is organised into') and specifies the payload ('with a service count for each'). It is clearly distinguishable from search_services and list_products, though it does not explicitly name the sibling it replaces.

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

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

Gives two concrete usage contexts: browse when keyword search is too narrow, and check coverage before a purchase. It implicitly names keyword search as the alternative, but stops short of explicitly saying 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 tell the agent this is a read-only, open-world listing, so the safety profile is covered. The description adds the shape of each returned item (free sample, representative purchase path), which is useful, but says nothing about ordering, result volume, or whether the listing is exhaustive. Adequate but not rich.

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, no filler. The definition of a product is front-loaded and the usage preference follows it, so the most decision-relevant information arrives first.

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 no output schema, the description carries the burden of describing returns and does so at a summary level (sample and purchase path per product). It omits how to drill into a product or retrieve full terms, though the sibling tools edge_get_free_sample and edge_get_report_terms plausibly cover that path.

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 there is no parameter semantics to convey; per the baseline for a no-arg tool this scores 4. The description correctly refrains from inventing filtering options that do not exist.

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

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

States a specific verb and resource ('List the packaged products') and immediately defines what a product is here — a bundle of specialist services composed into one buyer outcome — which separates it from the sibling service-level tools like edge_get_service and edge_list_families. An agent can identify the resource type without opening anything else.

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?

Explicitly gives a preference rule: 'Prefer these over assembling specialist services yourself when a product already matches the question.' That is a real when-to-use directive. It stops short of naming the alternative tools by name or stating when not to use it (e.g. when no bundle matches), so it lands just below a 5.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety and network scope are covered. The description adds value by enumerating the returned fields (id, name, description, family, price), which matters because there is no output schema. It stops short of describing ordering, pagination, or empty-result behavior.

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

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

Three short sentences with zero filler: purpose, return shape, and routing cue in that order. Nothing redundant with the schema or title.

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 two-parameter, read-only search with no output schema, the description covers purpose, usage context, and result fields adequately. Minor gaps remain around result ordering and how the catalogue is scoped, but nothing an agent needs 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?

Schema description coverage is 100%, so both 'query' and 'limit' are already documented with examples and bounds. The description adds no syntax, format, or matching-semantics detail (e.g. stemming, multi-word behavior) beyond what the schema provides, so 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?

States a specific verb and resource ('Find intelligence services by keyword'), which cleanly separates it from siblings like edge_get_service (fetch one by id) and edge_list_families (enumerate taxonomy). An agent can tell this is the keyword-discovery entry point without opening any schema.

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

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

Explicitly says when to reach for it: 'Start here when you know what evidence you need but not which service provides it.' That is a clear routing rule that implicitly names the alternative path (use edge_get_service once you know the id).

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real value by explaining that a service can be 'operational but working from evidence older than its freshness target' and that this is 'reported rather than hidden' – behavioral context the agent would not get from annotations alone.

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

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

Three tight sentences, no filler. The purpose is front-loaded, then the usage condition, then the parameter guidance – a logical order.

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

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

Complete enough for a read-only, single-param tool. The freshness/staleness distinction is the key non-obvious concept and it is captured. No output schema exists, but the description explains what is reported (availability and freshness), so no critical gap remains.

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

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

Schema coverage is 100%, so the serviceId parameter is already fully documented in the schema. The description reinforces the omit-vs-pass semantics for the platform summary vs single-service record, matching the schema baseline.

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

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

States a specific verb+resource: reporting per-service availability and data freshness. It is clearly distinguishable from siblings like edge_get_service (a lookup) and edge_list_products (enumeration), since this tool's job is health/probe status.

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

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

Gives a concrete when-to-use condition ('call this when a purchase matters and staleness would change the decision') and explains the operational-but-stale distinction. It doesn't name an explicit alternative sibling, but the context is specific enough to guide invocation.

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