AgentsCPA

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the mutation profile is partially covered. The description adds genuinely new context beyond those flags: the link is one-time, it transfers the key's statistics and earnings to an account, and it must not be shared with end users. Nothing contradicts 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?

Two tight sentences with no filler, and the core action is front-loaded. The audience-handling instruction is well placed at the end, but the whole definition is dense prose without structural separation for a tool whose main risk is misuse of the returned link.

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 one-parameter, no-output-schema tool this covers what is produced, what it attaches, why it is needed, and who may receive it. Minor gaps remain: nothing on link expiry or what happens if the link is used twice, which matters for a non-idempotent, one-time credential.

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 single parameter already documents the ak_ prefix, length, and the 'omit unless provided, never make one up' rule. The description adds only the framing that the key is anonymous and its stats/earnings travel with it, 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 concrete verb and resource: fetch a one-time sign-up link that attaches an anonymous agent key, with all its statistics and earnings, to an account. That is more specific than the sibling get_link and conveys the payload being transferred, though the description never names get_link to explicitly separate the two.

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 the triggering condition ('Sign-up is required only to withdraw money') and an explicit handling rule ('Give the link to your developer or the key owner, not to end users'). It stops short of naming alternatives such as get_link, so routing is implied rather than spelled out.

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 a prerequisite (offer must already come from search_offers) that annotations cannot express, which is useful. However, for a non-read-only, non-idempotent operation it says nothing about whether repeated calls mint duplicate links, whether links expire, or any rate limits — the annotations only say it is non-destructive and not open-world.

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, all earning their place: purpose with scope first, then the when-to-use condition, then the parameter contract. No filler or redundancy.

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

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

For a four-parameter tool with full schema coverage and no output schema, the description covers what it does, when, and which inputs to pass. The remaining gap is minor: it never indicates what the returned link looks like or whether it is reusable, which an agent may need to chain follow-up calls.

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 required parameters are already documented in the schema. The description restates the key constraints (offer_id from search_offers, full URL on the same site) but adds no new semantics such as accepted URL formats or what happens if the URL's site does not match the offer.

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 ("Get a tracked affiliate link") plus the target scope (a specific page — product, category, search results — on an offer's site). It names the sibling it depends on (search_offers) and clearly separates itself from discovery tools like search_offers/get_offer.

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?

"Use it when you know the exact page that answers the user's need" gives an explicit positive trigger and implicitly excludes the explore-then-decide case. It does not explicitly name the fallback (search_offers) for when the page is unknown, but the prerequisite phrasing makes the boundary clear enough.

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

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

readOnlyHint=true is consistent with a fetch, and the description adds value beyond annotations by disclosing that the payload contains sensitive commission data plus a policy constraint on surfacing it to end users. It does not cover behavior on an invalid or stale offer_id, which keeps it from a 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?

One sentence enumerating the return payload followed by a short constraint clause — no filler, and the highest-value information (what you get) is front-loaded before the caveat.

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 correctly compensates by listing the returned fields, and it flags the data-sensitivity constraint an agent needs before relaying results. Minor gaps remain around error behavior and whether language affects only the description field, but nothing essential to invoking the 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?

Schema coverage is 100%, so offer_id, language and agent_key are already documented in the schema, including the ak_ format and the "never make one up" warning. The description only reinforces that offer_id originates from search_offers and adds no new meaning for the optional parameters, 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 ("Get the full terms of an offer") and enumerates exactly what is returned: description, countries, commission type and rate, cookie window, hold period. It also anchors the tool to its sibling by saying the offer comes from search_offers, so an agent can distinguish it from get_link/get_stats without opening a 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 phrase "returned by search_offers" establishes the required prerequisite call ordering, and "For your own planning — do not show commission details to end users" gives an explicit audience restriction. It stops short of naming a when-not case or a fallback tool, but for a detail-lookup tool the guidance 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?

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add scoping context — which it does by making clear the figures are limited to "this agent key." It does not mention rate limits, default period behavior, or data freshness, so it adds some but not rich behavioral context beyond the annotation.

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 scope and metric list before the usage cue, with essentially no filler. Slightly denser metric enumeration would be the only improvement.

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 usefully enumerates the metrics returned, so an agent knows what to expect. Combined with the readOnly annotation and fully documented parameters, the only gap is the absence of any return-shape or aggregation granularity 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?

Schema description coverage is 100%, including the 1-90 day bounds and the explicit 'never make one up' warning about agent_key, so the schema carries parameter meaning. The description only references 'a period' without adding format or default details, which is the expected baseline when the schema does the heavy lifting.

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 gives a specific verb and resource ("Show this agent key's statistics for a period") and enumerates the metrics returned: tool calls, offers shown, clicks, conversions and earnings. It is clearly distinguishable from siblings like get_offer or claim_earnings, though it does not name those siblings explicitly.

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 states a concrete trigger: "Use when your developer or the key owner asks how the integration performs." That gives an agent a clear condition for selecting this tool. It stops short of stating when not to use it or pointing at alternatives, so it falls below the top band.

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 this as a non-read-only, non-destructive, idempotent, closed-world write, so the safety profile is covered. The description adds a genuine behavioral constraint beyond that: personal data must never go into the comment, and the effect is ranking improvement. It does not explain what a repeat report on the same offer_id does (overwrite vs. append), which is the main behavior an agent might get wrong.

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: what to send, why it matters, and the privacy rule. The action and its data source are front-loaded with no redundant or filler wording.

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 4-parameter tool with full schema coverage, annotations, and no output schema, the description covers purpose, data source, and the key privacy constraint. The remaining gap is failure behavior (e.g., invalid or unknown offer_id) and whether re-reports overwrite prior feedback.

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 all four parameters are already documented, including the reaction enum and the comment's no-personal-data rule. The description restates offer_id provenance and the enum values rather than adding syntax, format, or edge-case meaning, 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 (report) and resource (user reaction to an offer), enumerates the exact allowed reactions, and names the sibling tool that supplies offer_id. An agent can distinguish this from search_offers, get_offer, or get_stats 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?

The trigger is clear: call it after showing an offer, using the offer_id returned by search_offers, and it explains the downstream benefit (better ranking). It stops short of explicit exclusions such as when not to report or how to handle an offer the user never saw.

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 declare readOnlyHint=true; the description goes well beyond that by disclosing the output contract (links must be used exactly as returned, never invent prices or discounts), a behavior cap (at most 1-2 offers, once per 5 messages), a privacy constraint on input, and a graceful empty-result path. It also tells the agent how to behave after the call, which annotations cannot cover.

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?

Structure is strong: purpose first, then when-to-use, then exclusions, then input rules, then post-call behavior. The long parenthetical example list for triggers is the only slightly bloated part and could be trimmed without losing routing signal, so it falls just short of 5.

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 6-parameter search tool with no output schema, the description covers everything an agent needs: trigger conditions, exclusions, input privacy rules, and how to render results and degrade to a plain answer on empty results. Nothing material is left 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?

Schema coverage is 100%, so the baseline is 3. The description still adds meaning by instructing that 'need' be one short anonymized phrase with no names, phones, emails or quotes, and that the agent must pick the closest category itself — reinforcing agent-side responsibilities rather than restating field types. It doesn't add anything for budget or agent_key beyond the schema, which keeps it below a 5.

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 opening sentence names a specific verb and resource (products, stores, services, with ready links) plus a hard scope constraint: 'actually available in the user's country right now.' This is clearly distinct from siblings like get_offer (single offer lookup) or get_link, so an agent can route to it 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?

Explicit when-to-use is given with concrete trigger examples (recommendations, gift ideas, where-to-buy, shopping lists), and explicit when-not-to-use is enumerated: purely informational questions, sensitive conversations, users who asked for no ads, and a 5-message recency rule. This is the highest tier of routing guidance with named alternatives and exclusions.

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