research_submit

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

With no annotations provided, the description carries full responsibility. It discloses runtime (~90-300s), cost formula with concrete examples, asynchronous behavior (returns research_id immediately, runs in background), and the polling/fetching workflow. This is above and beyond what an annotation would typically provide, and gives the agent a realistic cost/benefit picture.

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 description is information-dense but each clause earns its place: purpose, duration, cost, usage constraint, async behavior, and follow-up steps. The cost details are slightly lengthy but valuable for decision-making. No filler or redundancy.

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?

Given the complexity (9 params, async, cost), the description covers the critical operational context: when to use, how long it takes, how much it costs, what it returns initially, and how to get the final result. It does not cover failure handling or cancellation, but with no output schema and strong sibling tool descriptions, this is a minor gap.

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%, so the baseline is 3. The description does not elaborate on individual parameters but does add cost-related context (e.g., 'full 20-query runs can exceed $1' connects to research_maximum_number_of_queries). This provides marginal added meaning beyond 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 opens with a specific verb and resource: 'Submit a Brave Answers RESEARCH job'. It clearly distinguishes this from the sibling tools by naming research_status and research_result as follow-up steps, and contrasts with the quick 'answers' tool. The scope (multi-iteration web research) is explicit.

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 an explicit usage condition: 'only use when the user explicitly requests deep research'. It also tells the agent what happens after submission (poll with research_status, fetch with research_result), effectively guiding when to use this tool versus its siblings. This meets the 'explicit when/when-not/alternatives' bar.

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