bbb_category

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

No annotations are provided, so the description carries full behavioral disclosure. It adds useful context by stating 'Credential-free public Better Business Bureau data' and that it returns the 'same normalized business-result shape as bbb-search.' It does not discuss rate limits or pagination behavior, but for a simple read-only browse operation the disclosed details are reasonably sufficient.

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 concise sentences with no filler. The main action is front-loaded, and each subsequent sentence adds a distinct useful detail: no free-text query, output shape parity with bbb-search, and credential-free access.

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 simple two-parameter tool with full schema coverage, the description is nearly complete. It explains what the tool does, how it differs from search, where the URL comes from, and what shape the response takes. It could mention pagination specifics beyond the default, but the 'page' parameter is already documented in the schema.

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 adds a bit of context by saying the url comes from a bbb-search result's related_categories and that browsing is by category and location, but this largely repeats schema information and adds no new semantic detail for the page parameter.

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 ('Browse') and resource ('Better Business Bureau category'), and clearly distinguishes itself from free-text search by stating it browses 'by category and location directly, without a free-text search query.' It also references the sibling bbb-search and its result shape, making the tool's purpose unambiguous.

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 this tool: when you have a category browse URL from a bbb-search result's related_categories, and it explicitly contrasts with free-text search. It references bbb-search as the source of the URL and notes the same normalized output shape, but it does not formally name an alternative for free-text queries or state exclusions.

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