brave_search

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

With no annotations, the description carries the behavioral disclosure burden and does so by detailing what the response contains (normalized results, pagination, related queries, discussions, videos, knowledge card) and the conditionality ('when Brave includes one'). It also reveals locale defaulting behavior (country=us, lang=en-us). It does not mention rate limits, authentication, or a read-only guarantee, so it is not a perfect 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?

Three sentences with zero fluff: the first identifies the operation and payload, the second gives date-filter guidance, the third states locale defaults. All information earns its place and is front-loaded.

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 7-parameter search tool with no output schema, the description covers the key things an agent needs: what results come back, how pagination works, how to filter by date, and what the locale defaults are. It stops short of documenting error behavior, rate limits, or explicit pagination iteration, but it is sufficient for a reliable first call. Given the rich schema, this is a complete-enough definition.

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% with descriptive parameter entries, so the baseline is 3. The description adds value by explaining the relationship between time_range and date_from/date_to ('Use time_range for preset ranges or date_from/date_to for a custom YYYY-MM-DD range') and reiterating locale defaults, which helps an agent choose the right filter mechanism. It does not redefine individual parameters, keeping the description lean.

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 'Search Brave' and specifies that it returns 'normalized web search results from Brave Search for a query string' – a precise verb+resource pairing. It enumerates the response components (offset-based pagination, related queries, discussions, videos, right-side knowledge card), which distinguishes it from vertical search siblings like brave_images, brave_videos, and brave_news. The scope is 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 gives clear context: this is a general web search returning web results plus related blocks, so an agent can infer it is the right tool for open-ended web queries. It adds concrete parameter usage ('Use time_range for preset ranges or date_from/date_to for a custom YYYY-MM-DD range') and states locale defaults. However, it does not explicitly name alternatives like brave_images, brave_news, or brave_videos for vertical searches.

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