start_agent_run

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

With no annotations supplied, the description carries the full burden and does so well: it discloses the pre-flight failure mode (insufficient IQ credits aborts before starting), the inline polling window (up to 2 minutes), the expected total latency (3-5 minutes), and the two possible return shapes (full results vs. run ID plus a follow-up instruction). These are exactly the cost, timing, and failure facts an agent needs before committing to a long-running operation.

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?

Four sentences, front-loaded with purpose, then the pipeline, then the failure/latency/return contract. Every sentence carries operational information an agent needs, and the parenthetical '(typical run takes 3-5 minutes)' pre-empts the obvious follow-up question about the 2-minute poll window.

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 an eight-parameter, long-running async tool with no annotations and no output schema, the description covers what matters: what it does, what it costs, how long it takes, how it can fail, and what comes back in each outcome. Return-value explanation is present precisely because no output schema exists to supply it.

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 all eight parameters are already documented in structured data, which sets the baseline at 3. The description only reinforces the 'question' parameter as plain English; it adds nothing about mode selection, platform defaults, time_window syntax, or the fact that the field named available_credits actually controls reasoning effort rather than a credit balance.

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?

States a specific verb and resource ('Start a Rolli Agent investigation') and then spells out the full pipeline: plan search strategy, query Rolli IQ across platforms, analyze posts, produce a markdown report with signals, evidence links, and confidence rating. An agent can distinguish this from siblings like get_agent_run, rerun_agent_run, or expert_search without opening any schema.

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?

Gives clear conditions for calling it (submit a plain-English question) and explicitly routes to get_agent_run when the inline poll window expires. It also flags the credit-balance precondition. It stops short of stating when NOT to use it versus rerun_agent_run, cancel_agent_run, or the expert_search/keyword_search alternatives, so it is strong but not exhaustive.

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