jb_run_search

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

With no annotations provided, the description carries the full burden — and it delivers. It discloses the mutation side effect, persistence ('leaves a real saved search in the workspace, visible to the whole seat'), hidden costs (DOM page walks per 15 candidates), and the matchRate cross-search non-comparability caveat. This is exactly the kind of behavioral context an agent needs and that annotations would normally supply.

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?

Well front-loaded — purpose, write-warning, and confirmation instruction all land in the opening. But it runs several dense paragraphs and includes persuasive detail (the 42/44 versus 22/30 head-to-head benchmark) that, while informative, goes beyond what a call-time decision strictly needs. Mostly earns its sentences but is longer than ideal.

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 tool with no output schema and no annotations, coverage is unusually extensive: side effects, confirmation requirement, prompt construction strategy, and result-comparability caveat are all addressed. The one gap is that the description never says whether the created search's ID/reference is returned, which matters for chaining calls to the sibling ID-based tools afterward.

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 baseline is 3. The description adds real semantic depth to the prompt parameter beyond the schema: it explains that Juicebox extracts filters from prose, states what to include (seniority, geography, metric, etc.), and dictates explicit exclusions. This materially changes how the agent would construct the prompt, going beyond the schema's field list.

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?

Leads with a specific verb+resource+outcome: 'CREATE and RUN a new Juicebox search from a natural-language prompt, then return its ranked candidates.' It explicitly distinguishes itself from the read-only siblings with 'This is the ONLY tool here that WRITES,' so an agent can immediately separate it from jb_list_searches, jb_get_results, and jb_count without opening their schemas.

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?

Provides strong when-not guidance: confirm with the user before calling, do not call speculatively in a loop, do not tune for a small pool. It signals the write nature versus siblings ('ONLY tool here that WRITES'), making the read-vs-write split clear. However, it never names the sibling alternatives explicitly with conditions (e.g., 'use jb_get_results for an existing search'), leaving that substitution implicit rather than explicit.

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