Decision Intelligence

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

Annotations already indicate non-read-only and open-world behavior, and the description adds the notable cost/payment detail ('$0.08/call, x402 (USDC on base)') and the 'unsent action findings' outcome. It does not fully explain side effects, but the annotations lower the burden and this adds useful context beyond them.

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

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

The description is a single sentence, front-loaded with purpose, followed by a concise pricing note. Every element serves a purpose, and there is no redundancy 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?

While the schema is rich, the description omits important operational context such as the mutual exclusivity of rows/datasetId, the deterministic analysis options, and the absence of an output schema. For a complex 13-parameter tool, a bit more prose would help, but the schema mitigates the 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 input schema covers 100% of parameters with descriptions, so the schema does the heavy lifting. The tool description itself adds no parameter-level meaning beyond what is already in the schema, warranting 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 the tool compares supplied app reviews around a release and returns regression and unsent action findings, using a specific verb and resource. This is distinct from sibling tools (competitor-ad-change-brief, pricing_info, us-map-retail-evidence) which address unrelated domains.

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 context that the tool is for analyzing app reviews around a release, but it doesn't explicitly say when not to use it or name alternatives. The sibling tools are obviously different, so the context is sufficient for basic selection.

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 reveals useful behavioral traits: 'deterministic' outputs and the cost/payment model ($0.10/call, x402). However, it does not disclose that the tool likely calls an external model (openrouterApiKey), whether any external state changes occur (readOnlyHint is false and openWorldHint is true), or how 'unsent actions' are handled. With annotations providing only limited safety info, the description adds some but not sufficient transparency.

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 functional sentence followed by pricing info. It is front-loaded with the primary action and output, contains no filler, and every clause adds meaningful information. Ideal conciseness.

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?

This is a highly complex tool with 11 parameters, nested objects, conditional allOf logic, a oneOf choice between rows and datasetId, and no output schema. The description covers none of this, leaving the agent to guess input structure, return format, and operational semantics. It is severely under-specified for its complexity.

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

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

Schema description coverage is 0%; the description provides no explanations for any of the 11 parameters. The phrase 'supplied ad evidence' vaguely hints at the rows/evidence fields, but it does not help an agent understand the required coverage object, the rows-versus-datasetId oneOf, analysisModel, sourceContract, or pricing constraints. The complex conditional schema demands far more 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 states a specific verb ('Compare') and resource ('supplied ad evidence') and explicitly names the three outputs: deterministic changes, baseline state, and unsent actions. This clearly differentiates the tool from sibling tools (app-release, pricing, map-retail), which operate in entirely different domains.

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

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

The description provides no guidance on when to use this tool over alternatives, no exclusions, and no context about typical scenarios or prerequisites. It only states what the tool does, leaving the agent to infer usage entirely from the tool name and schema.

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, and the description aligns with this by noting the operation is 'Free' and involves listing. It adds meaningful behavioral context beyond annotations: the tool returns price, payTo address, and network, and is intended as a first step before wallet preparation. No contradiction exists.

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

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

The description is two sentences with no fluff. It front-loads 'Free' and the core action, then adds the key usage context. Every word 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 tool with no parameters and no output schema, the description fully covers what the tool does, what it returns, and when to call it. It is complete for its 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 has zero parameters, so the baseline is 4. The description correctly does not need to explain parameter semantics, and there are no parameters to compensate for.

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 'list' and clearly identifies the resource: 'every paid tool in the 'decision-intelligence' bundle'. It also specifies the exact details returned (price, payTo address, network), making the tool's purpose unambiguous and distinct from its unrelated 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 phrase 'Call this first if you don't have a wallet ready yet' explicitly states when to use the tool, providing clear contextual guidance. However, it does not mention alternatives or explicitly state when not to use it, so it stops short of a 5.

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

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

Annotations already provide the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint flags, so the bar is lower. The description adds the cost and the fact that it produces findings, but it does not elaborate on side effects, external calls, or the meaning of openWorldHint in practice. It does not contradict the annotations, so a 3 is appropriate.

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 plus a pricing note. It is concise and front-loaded with the purpose, and the cost information is relevant. It could be slightly longer to cover key usage details, but for what it does include, it is efficient and well-structured.

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 9 parameters, nested objects, a oneOf conditional, and no output schema, the description is far too brief to be complete. It does not explain the two input modes (rows vs datasetId), what the findings look like, or any prerequisite setup. The schema is complex and the description leaves most of that unexplained, making it hard for an agent to invoke correctly without additional guidance.

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 11% (just requestId has a description). The tool description does not compensate for this lack of parameter documentation. It mentions 'supplied US retail evidence' but does not explain the crucial oneOf between rows and datasetId, the datasetCoverage requirement, or the option fields. The complex schema is underspecified, and the description doesn't help.

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

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

The description uses a specific verb ('Process') and states the resource ('supplied US retail evidence') and the outputs ('MAP, availability, baseline, and review findings'). This is clear and distinct from the sibling tools, which are about app releases, competitor ads, and pricing info. However, it does not explicitly say how it differs from pricing_info, so it loses a point for not fully distinguishing itself.

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?

There is no guidance on when to use this tool versus the alternatives, nor any prerequisites or exclusion criteria. The description only says to process retail evidence but does not indicate when this is the right choice or when another tool would be better. This makes it hard for an agent to select it confidently.

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