run

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

No annotations exist, so the description carries the full burden, and it does disclose a lot: per-item independent ranking, the outcome branches (best tool runs / 'do it yourself' / connect a key), that 'ask' mode runs nothing, and the critical constraint that queries are literal and the tool cannot see the chat. Remaining gaps are failure semantics across a batch, async/pagination behavior, and what happens if an owed report is not supplied.

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 critical directive leads the description and each subsequent line covers a distinct concern (item shape, reports, mode), so it is front-loaded and largely waste-free. It loses a point for telegraphic fragments like 'reports: owed scores' and '<run>/<n>' that trade clarity for brevity without a reader already versed in the system.

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?

This is a complex routing tool with no output schema, no annotations, and 0% schema coverage, so the description must carry everything — and it omits the shape of what comes back, how a run id is obtained for the reports format, and how it composes with sibling tools like fetch_result and report_outcome. Adequate to invoke correctly in the common case, but not complete for a tool of this complexity.

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 0% and the schema exposes items as an untyped array, so the description must do the work — and it largely does, defining item forms ('strings, or {query, facets?, tool?}'), the literal/self-contained nature of query, the purpose of tool, the score enum for reports (full|partial|useless|blocked), and mode's default and values. Gaps remain: 'facets?' is never explained, 'owed scores' is undefined, and the '<run>/<n>' reference format is never introduced.

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 states a specific role: this is the single entry point for all outside lookups (search, page, third-party API), and explains the mechanism — each item is ranked, the best tool runs, and its result returns. That is a clear, non-tautological statement of what the tool does, well beyond the bare name 'run'. It does not, however, differentiate itself from siblings such as ranking, describe, or fetch_result, which sit in the same lifecycle.

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?

Strong operational guidance: 'never do one yourself first', 'One item per lookup; batch all known lookups in one call', the auto-vs-ask mode split ('nothing runs; the user picks from the top 3'), and explicit when-not behavior ('needs a key = stop and ask the user, never do it another way'). What is missing is routing against sibling tools — it never tells the agent when to use run versus fetch_result or report_outcome.

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