bbb_scamtracker_state_stats

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

With no annotations provided, the description carries the full burden, and it delivers: it discloses that the tool calls the same JSON API the BBB heatmap dashboard frontend uses rather than scraping HTML, and explicitly states it is credential-free public data. These are meaningful behavioral traits beyond the schema. It stops short of covering data freshness, caching, or response-size caveats, but for a simple read-only fetch the disclosed provenance and auth requirements are the most valuable context.

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 zero waste: purpose is front-loaded, return values are listed compactly, and implementation details (JSON API provenance, credential-free) are appended without bloat. At roughly 55 words, every sentence earns its place and the structure is optimal for agent scanning.

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 one optional parameter, no output schema, and no annotations, this description is nearly complete: it covers scope, output fields, data source, and access requirements. The only notable gap is the ambiguous unit/format of the period parameter, which is shared with the schema rather than an omission unique to the description.

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 the baseline is 3. The description's 'for a given time window' only restates the schema's 'Aggregation window' without adding the unit or accepted format (e.g., whether 90 means days, or if date ranges are allowed). The parameter is adequately documented by the schema; the description adds no meaningful new semantics.

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 opens with a specific verb+resource ('Get Better Business Bureau Scam Tracker state/province aggregate stats') and enumerates the exact output fields: report counts, dollar losses, per-capita rates, year-over-year change, and top scam-type breakdown. The state/province aggregation scope clearly distinguishes it from siblings like bbb_scamtracker_search and bbb_scamtracker_detail, which handle individual reports.

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 implies when to use the tool—when aggregate state/province statistics are needed rather than individual scam reports—but it never explicitly names alternatives or states when-not-to-use. No direct routing guidance to bbb_scamtracker_search/detail is provided, leaving the agent to infer the distinction from the aggregation language alone.

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