Quote a trend search

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

Annotations already cover the read-only, non-destructive profile, and the description adds real context: quoting is free and a repeat query from the last hour prices at 0, which is valuable pricing/caching behavior. The trailing 'Free.' is ambiguous — it is unclear whether it refers to the quote call or the search itself, and no other behavioral traits (e.g., quote expiry, failure modes) are disclosed.

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 short sentences with no padding, and the core 'zero when cached within an hour' fact is front-loaded. The structure is awkward as a sentence fragment and the final 'Free.' reads as an afterthought rather than a clear 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?

With four parameters, no output schema, and thin schema descriptions, an agent needs to know what the quote returns and what drives the price — neither is explained. The description covers the zero-cost cache case but leaves the normal paid path and the meaning of platform/posted_within_days entirely unspecified.

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 25% (only 'language' is documented), so the description carries the burden of explaining the remaining parameters — but it says nothing about 'keywords', 'platform', or 'posted_within_days'. At most, 'the same query' faintly implies that the full parameter set determines cache hits, which is far short of compensating for the coverage gap.

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 verb 'Price' plus the named resource 'find_trends' makes it clear this tool returns a cost estimate for a trend search, and it explicitly distinguishes itself from the priced sibling. However, the fragment 'Price find_trends:' is telegraphic and doesn't state outright that it returns a quote without running the search.

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?

Naming find_trends implies the caller should quote before running a trend search, and the 'last hour' cache rule hints at when a quote will come back at zero. But there is no explicit when-to-use instruction, no statement of what to do if the quote is rejected, and no mention of the other quote_* siblings in the list.

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