Bob Research Tools

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, but the description adds genuinely non-obvious behavior: an x402 payment is required per call, typical latency is 2-5 seconds, output is truncated at 8,000 characters, and failed reads are not charged. These cost/failure semantics go well beyond what the annotations convey. It stops short of 5 only because it doesn't describe pagination or whether truncation is signalled beyond the boolean field.

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?

One dense paragraph, front-loaded with what is returned and its shape, then usage routing, then input, then cost/failure. Every clause carries information an agent needs; no filler.

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 one-parameter tool with no output schema, the description supplies the return structure, the truncation limit, latency expectations, payment requirement, and failure behavior, which is nearly everything needed to call it correctly. The only minor gap is not saying whether 'truncated' is the sole signal of cut-off content or whether retries/alternatives exist for long pages.

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?

There is a single parameter with 100% schema description coverage; the schema already states it must be a public http/https address and that private or local addresses are refused. The description's 'Input: a public http or https URL' restates that constraint rather than adding syntax or format detail, so the baseline of 3 applies.

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 (returns/extracts) and resource (main text of one public web page), plus the exact output shape {url, markdown, truncated} and the size cap. It explicitly distinguishes itself from bob_summarize, so an agent can separate it from siblings 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 an explicit selection rule: 'Use it when you need the page's own words; use bob_summarize for a short version.' This names both the condition and the alternative tool, leaving nothing to inference.

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

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

Annotations cover the safety profile (readOnly, openWorld, non-destructive), and the description goes further with latency expectations (4-9 seconds), the x402 payment requirement, and the important billing guarantee that failures or invalid input are not charged. It does not mention rate limits, retry behavior, or source-quality characteristics, but the operational disclosures given are well beyond what the annotations provide.

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 compact sentences, front-loaded with what the tool does and its output contract, followed by routing, input constraints, and billing. Every sentence carries information, though the payment/latency sentence packs several distinct facts that could be separated for faster scanning.

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 single-parameter tool with no output schema, the description supplies the missing return contract (verdict values, explanation, sources), the expected duration, the payment model, and failure semantics. An agent has everything needed to decide, call, and interpret results.

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% and the single parameter is fully documented in the schema, including the 1-500 character bound and 'written as a statement'. The description restates those same constraints without adding format, syntax, or interpretation guidance, so it adds no meaning beyond the schema — baseline 3.

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 ('Checks one factual claim against the live web') and immediately gives the return shape {verdict, explanation, sources} with the verdict enum values. It also names the sibling it is not ('use bob_research for open questions'), so an agent can route without opening either 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?

Explicit when-to-use ('verify a specific statement') paired with an explicit alternative and the condition that selects it ('use bob_research for open questions'). Nothing about tool selection is left to inference.

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

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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), but the description adds substantial context the annotations cannot: typical latency of 4-9 seconds, the response shape, the x402 payment requirement per call, and the important failure semantics that an invalid or timed-out call is not charged. This is exactly the kind of operational detail an agent needs before spending money.

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 dense sentences, front-loaded with purpose, then routing, then contracts (input, return, cost, failure). No filler; every clause carries information an agent would otherwise have to guess.

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?

Despite no output schema, the description declares the return shape {answer, sources}, the input bound, latency, payment, and failure/refund behavior. There is no meaningful gap for an agent deciding whether and how to call this tool.

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?

Only one parameter and schema coverage is 100% – the schema already documents 'q' as a 1-to-500 character question, and the description's 'Input: a question of 1 to 500 characters' merely restates it. Baseline 3 is correct when the schema carries the semantics and the description adds nothing new.

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+resource+scope: answering one open research question from the live web, returning a short synthesized answer plus source URLs. It explicitly distinguishes itself from bob_search ('raw ranked links') and bob_factcheck ('verify a specific claim'), so an agent can route 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 explicit when-to-use ('want a synthesized answer') and names two alternatives with the conditions that select them (raw links vs. claim verification). Nothing about tool selection is left to inference.

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

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

Annotations cover the safety profile (readOnly, openWorld, non-destructive), yet the description adds material context the agent could not infer: result count (5 per call), latency (usually under a second), and the x402 payment model including the no-charge-on-failure guarantee. That payment/failure behavior is exactly the kind of operational detail that changes invocation decisions.

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?

Front-loaded and dense: capability, usage routing, payment, and failure semantics each earn their sentence. The only near-redundancy is restating the query length constraint already in the schema, a small but non-fatal padding.

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?

With no output schema, the description correctly supplies the return shape ({query, results:[{title,url,snippet}]}), result count, timing, and billing behavior. Nothing an agent needs to call this and interpret the response is missing.

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% for the single parameter, so the baseline is 3. The description restates the 1-to-500 character limit but adds no syntax, formatting, or example guidance 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?

States a specific verb and resource ('Runs a web search and returns ranked results') and immediately names the return shape, so the agent knows exactly what it gets. It also contrasts itself with bob_research, making it distinguishable from siblings without opening 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?

Explicit routing rule: 'Use it when you want raw links to read yourself; use bob_research for a written answer.' This is a clear when-to-use paired with a named alternative and the condition that selects it.

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

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

Annotations already cover the read-only/open-world safety profile, but the description goes well beyond: it discloses the per-call x402 payment requirement, expected latency (3-6 seconds), the exact failure modes (page unreadable or invalid URL), and that failures are not charged. This is unusually rich behavioral context for a read tool.

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 tightly packed sentences, each carrying distinct information: purpose, alternative routing, input constraint, and cost/failure semantics. Front-loaded with the core capability and zero filler.

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?

Although there is no output schema, the description specifies the return shape ({url, summary, key_points}), the summary length, key-point count, latency, payment model, and failure handling. Nothing an agent needs to call it correctly is missing.

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% for the single url parameter and the schema already documents that it must be a public http/https address. The description's 'Input: a public http or https URL' largely restates that, so the baseline 3 applies with no added format or syntax detail.

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 ('Condenses one public web page into an 80-word summary') plus the output shape, and explicitly contrasts with bob_extract. An agent can distinguish it from all siblings without opening a 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 an explicit when-to-use ('when you want the gist') and names the alternative tool with the condition that selects it ('use bob_extract to get the page's own text instead'). No inference required.

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