Best ads for a budget

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

Annotations already establish the safe read-only profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description still adds substantial behavior: it scans the newest N pages capped at budget, computes a deal_score with named reasons and penalties, drops implausible/bait ads into skipped_implausible, opens the top 6 ad pages for extra fields with an explicit caveat about the rest, and reports an empty list with a note on unrealistic budgets. This is unusually rich disclosure of algorithm and side data beyond 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 purpose is front-loaded in the first line before any implementation detail, and no sentence is purely decorative. It is dense to the point of being run-on, with heavy parenthetical stacking (median, photos, freshness; penalties...), which slightly impedes scanning but does not bury the lead.

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 15 parameters, nested filters, and no output schema, the description carries the burden of explaining returns and it does so: best_value, deal_score, reasons, skipped_implausible, caveat, and note are all named. Combined with the usage and failure-mode guidance, an agent has everything needed to call this 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 already 100%, so the baseline is 3, but the description genuinely extends semantics: it clarifies that budget interacts with market_median/budget_median and that query/keywords determine whether bait words are kept rather than filtered, and that a mixed category makes the median meaningless. That adds meaning not encoded in the schema.

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

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

The description states a precise verb (scan/return) and resource (ads within a budget) and even names the two ranked sub-lists it produces: 'best-value ads' and 'the most you can get'. This is far more specific than a tautology and an agent can tell it is a budget-constrained deal ranker. It stops short of distinguishing itself from close siblings like dv_cheapest or dv_find_deals, which is the only reason it is not 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 real invocation guidance: 'Use a narrow query or brand: a mixed category's median means nothing', and routes onward with 'Next: dv_appraise, dv_post'. It also explains the failure mode ('An unrealistic budget returns an empty best_value with a note'). No explicit when-not or direct sibling exclusion is offered, so a 4 rather than 5.

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