AIsa Web Search & Research

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

Annotations already declare destructiveHint=true and openWorldHint=true, so safety is covered. The description adds valuable behavior: independence of items (one failure doesn't cancel others) and per-call billing. These are not derivable from annotations and help the agent set expectations.

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 short sentences with zero filler. The action and limit are front-loaded. The phrase 'tool-router's batch_use' is redundant since it restates the tool name, but it's a minor flaw. Overall it is concise and well-structured.

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 annotations covering destructive behavior and an output schema presumably describing results, the description covers the key operational aspects: concurrency limit, independence, and billing. It doesn't mention error reporting formats, but those likely live in the output schema. It is sufficiently complete for a batch 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?

Schema description coverage is 100%, so the schema fully documents each parameter. The description adds no parameter-specific details. The calls parameter's description already explains the structure and batching context, so the baseline of 3 applies; the description doesn't need to compensate.

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 clear action (execute) and resource (operations) with a concrete limit (up to 20) and concurrency. It doesn't explicitly name the sibling 'use' for single operations, but the distinction is clear enough from the concurrency and limit. The redundancy of 'tool-router's batch_use' is minor.

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 no guidance on when to use this tool versus the sibling 'use' tool. The schema note about 'steps at the same execution_level of a plan go in one batch' is helpful, but it lives in the schema, not the description. The description only implies batching via concurrency but doesn't state when to choose it over the single-operation alternative.

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 declare readOnlyHint=true and destructiveHint=false. The description adds meaningful context: it is free, stops before any spend, and explains how price.model varies (quoted, list, dynamic, composed). It also clarifies that suggested_max_price_usd has headroom. This goes beyond the annotation flags and gives the agent a clear model of what happens.

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 moderately long but well structured: it opens with the core purpose, then explains the price model in a dedicated paragraph. No redundancy or filler. It front-loads the most critical information (contract fields) and then gives necessary detail about price semantics. Slightly dense but not overly verbose.

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?

The tool has an output schema, so return values need no description. The description covers the key behavioral aspects (no spend, pricing models, max_price headroom) and clarifies edge cases like routes without a price. For a read-only informational tool, this is complete enough for an agent to use it correctly.

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 parameters are already documented. The description adds some nuance, such as how arguments affect pricing and that required parameters may be needed before a price can be quoted. It also clarifies with_quote's purpose (one round trip, spends nothing). These are useful but not essential given the schema's completeness.

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 purpose: returning the full contract of one or more operations, including schemas, read_only, side_effects, price, and known_pitfalls. It clearly distinguishes this from executing operations (use, batch_use) and from discovery (search, list_categories). The verb 'get' and the noun 'details' align with the title, and the first sentence 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 implies the tool is used to assess an operation before spending (e.g., 'A quote authenticates like a call but stops before any spend'), and the schema says 'One operation_id from search', hinting at a flow. However, it never explicitly states when to choose this over siblings like use or search, nor does it give exclusions. The guidance is implied, not stated.

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?

Even with readOnlyHint and idempotentHint annotations present, the description adds meaningful behavioral detail: it lists the returned envelope fields, defines the terminal statuses, and describes the polling loop. It also clarifies the read-only scope and what `output` contains on success. There is no contradiction with annotations.

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 the action and resource, with every sentence earning its place: source endpoint, return envelope, polling semantics, and read-only exclusion. 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?

For a one-parameter, read-only poller with an output schema, the description covers invocation, expected response shape, terminal states, and success payload structure. Nothing essential for correct use 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?

The input schema already fully documents the single `jobId` parameter with the same meaning, and schema description coverage is 100%. The description restates that the job ID comes from the submit call, but adds no additional format, constraints, or edge-case semantics beyond the schema. Baseline 3 is appropriate.

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 'Fetch an Agent run,' naming the exact verb and resource, and ties it to `post_exa_agent_runs` by `jobId`. It explicitly frames the tool as read-only ('Reads a run only; it cannot start one'), distinguishing it from sibling submit tools like `post_exa_agent_runs.

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 a clear usage pattern: fetch the run submitted by `post_exa_agent_runs`, then 'Repeat until `status` is `completed`, `failed` or `cancelled`'. It also states the when-not case, 'it cannot start one', which routes creation to the correct sibling. This is explicit and actionable.

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 declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful non-obvious behavior: the return envelope fields (`id`, `status`, `createdAt`, `completedAt`, `pricing`, `output`, `error`), the polling loop expectation, and the success output shape (`array of documents with markdown and metadata`). This goes well beyond what 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?

Three tight sentences deliver the action, the returned data structure, and the operating loop, with zero filler. The core purpose is front-loaded in the first sentence, and each subsequent sentence adds distinct value.

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 one parameter, full schema coverage, an output schema, and annotations covering safety, the description supplies the only missing operational detail: polling until terminal status and interpreting the output array. Nothing needed for correct invocation is omitted.

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 param `jobId` is described as 'The job id returned by the submit call.' The description adds little beyond that ('by its jobId' and the reference to the submit tool). The schema already carries the load, so a baseline 3 is appropriate.

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 uses a specific verb ('Fetch') with a precise resource ('batch scrape job') and identifies the submission source (`post_firecrawl_batch_scrape`). The final clause 'Reads a job only; it cannot start one' clearly differentiates it from sibling creation tools like post_firecrawl_batch_scrape and complements the similar poll tool get_firecrawl_crawl_job.

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 clear usage context: it fetches a job created by post_firecrawl_batch_scrape, and instructs the agent to 'Repeat until status is terminal'. It also states a non-use case ('cannot start one'). It does not explicitly compare itself to get_firecrawl_crawl_job, but the batch-scrape scope and naming make the distinction straightforward.

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 declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds useful context: the polling loop pattern, the terminal statuses, the output shape on success, and the performance characteristic ('under a second'). It doesn't contradict annotations.

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 compact, front-loads the core action, and every sentence earns its place: what it fetches, what the response looks like, when to stop polling, performance, and the read-only boundary.

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 polling tool with a rich output schema and strong annotations, the description covers everything an agent needs: how to call it, what to expect, when to stop, and how it relates to the submission tool. The output schema already documents return values, so the description doesn't need to.

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 jobId is already described as 'The job id returned by the submit call.' The description reinforces this by saying 'by its jobId' and referencing the submission tool, but it doesn't add substantial new 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 states a specific verb ('Fetch'), a specific resource ('a crawl job submitted by post_firecrawl_crawl'), and the key identifier ('jobId'). It clearly distinguishes this from the submission tool and other sibling tools by noting it only reads a job and cannot start one.

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 explicitly says to repeat polling until status is completed, failed, or cancelled, and notes that polling is cheap and fast. It also explicitly states what this tool cannot do ('it cannot start one'), which helps an agent choose between this and post_firecrawl_crawl.

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 provide readOnly, idempotent, and non-destructive hints, and the description adds valuable behavior: the exact response envelope, terminal statuses, and the shape of successful output. This gives the agent a clear polling contract beyond the annotations.

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 reasonably compact, front-loaded with the core action, and every sentence adds useful guidance: origin, return shape, polling condition, and read-only caveat. Nothing is wasted.

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 polling tool with an output schema and strong annotations, this description is complete. The polling loop, terminal states, output expectations, and boundary against job creation are all covered.

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 `jobId` parameter, so the schema already carries the semantic weight. The description's reference to `jobId` adds no real meaning beyond what the schema says; it simply reinforces that the id comes from the submit call.

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 action ('Fetch') on a specific resource (Oxylabs LLM job) and ties it to the submitting sibling, `post_oxylabs_llm`. It also distinguishes itself from job creation by explicitly saying it 'cannot start one.'

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?

Explicitly tells the agent when to repeat calls ('until status is completed, failed, or cancelled') and what success looks like. It also names the submitting tool and clarifies this is a read-only polling operation, which distinguishes it from starting or cancelling jobs.

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 declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: the tool is free, requires no key, and can direct users to a category-specific endpoint that lists tools directly rather than through search.

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 moderately detailed but every sentence adds useful information: output scope, cost/auth, sibling differentiation, and endpoint usage. It is slightly longer than strictly necessary but remains well-structured and front-loaded with the core purpose.

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 zero-parameter, read-only tool with an output schema and safety annotations, the description is complete. It covers what the tool returns, the free/no-key access model, and provides the category endpoint for specialized use, leaving no essential gap for an agent to call it correctly.

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?

The tool has zero parameters, so the baseline is 4. The description includes a <category> placeholder only in the endpoint examples, not as a tool parameter, which is appropriate supplementary guidance rather than a parameter-semantics gap.

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 clearly states what the tool does: it presents the AIsa catalogue at a glance, including categories, servers, tool counts, and a dedicated category endpoint. It also distinguishes itself from search by explaining that the endpoint lists tools directly instead of via search.

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 provides clear usage context: use list_categories for a catalogue overview, and use the provided endpoint when you only need one category. It explicitly contrasts with search ('instead of via search') and notes tool-router has no equivalent, although it does not exhaustively cover all sibling alternatives.

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 declare readOnlyHint/openWorldHint/idempotentHint, and the description layers substantial extra context on top: server-pinned model injection with no override, Claude's autonomous search triggering (max_uses default 5), the full response block structure (server_tool_use, web_search_tool_result, text with citations), and the exact pay-as-you-go billing formula including the no-markup and failed-search-not-billed rules. No contradiction with the readOnly/openWorld annotations.

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?

Purpose is front-loaded in the first sentence, and the text flows logically from mechanism → response format → billing → alternatives. It is long, but every section earns its place given the cost model and multi-block response that need explanation; nothing is filler. Slightly dense, which costs it a perfect score.

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?

Even with a rich output schema and annotations present, the description covers everything an agent needs to call this correctly: billing behavior (including edge case of unbilled failed searches), the non-overridable server-pinned model, the autonomous search trigger count, and the response block layout. Nothing material 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%, so the baseline is 3. The description adds value by linking parameters to behavior — noting messages is 'same format as the Anthropic Messages API' with the user turn holding the question, and explaining that max_tokens is 'required by the upstream Messages API' — contextual rationale the schema lacks. It goes slightly beyond pure schema restatement.

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-resource pair ('Ask a question and get an answer that Claude wrote after searching the live web') and explicitly names the two closest siblings it is not — post_tavily_search and post_openai_websearch_search. An agent can distinguish this from a dozen sibling search tools 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?

It states the exact use case ('when you want a written, cited answer grounded in current web content') and gives two concrete alternatives with the conditions that select them: open-web research returning ranked links/page text → post_tavily_search, OpenAI-model equivalent → post_openai_websearch_search. This is explicit when/when-not guidance.

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?

The description clearly describes a mutating submission operation that creates a background run and bills $0.10, but the annotations declare readOnlyHint=true. That is an annotation contradiction: submitting a run and receiving HTTP 202 is not a read-only action, even though the description is otherwise rich about async behavior and polling.

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 front-loaded with the core action and then moves through required inputs, lifecycle, pricing, and alternatives. It is long but each section earns its place, with only minor redundancy like repeating that the run is asynchronous after already saying it works in the background.

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 complex asynchronous submit-plus-poll tool, the description covers everything needed to call and monitor it: required parameters, job envelope fields, polling endpoint, latency expectation, pricing, and the sibling alternative. The output schema handles return-value details, so nothing critical 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?

The schema already has 100% coverage, so the baseline is 3, but the description adds real meaning: 'effort' trades depth against time, 'outputSchema' shapes the result, 'dataSources' restricts where the agent looks, and 'previousRunId' continues an earlier run. It also reinforces that query and Idempotency-Key are required and that a fresh key is needed per distinct task.

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 action and resource: hand a research task to a background agent and get an async run. It also names distinct use cases and contrasts with post_exa_answer, so an agent can tell this tool apart from its siblings.

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 explicit when-to-use guidance ('Use it when a report is the deliverable'), when-not-to-use guidance ('For an answer you read in one sitting, post_exa_answer returns in about two seconds'), and names get_exa_agent_run as the polling follow-up. It also notes flat pricing, which helps an agent decide between this and Firecrawl crawls.

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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond these by disclosing the output structure (requestId, answer, citations with id/title/url, costDollars), expected latency (2.1 seconds) and citation count (8), and flat billing ($0.08). It also clarifies the roles of text and outputSchema. No contradictions with annotations; the description adds substantial behavioral context.

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 compact yet information-dense. It front-loads the core purpose, then systematically covers parameters, output, performance, cost, and sibling comparisons. Every sentence earns its place—there is no filler, and the structure leads the agent from the basic action to advanced trade-offs without 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?

For a tool with 4 parameters, an output schema, cost implications, and several siblings, the description is remarkably complete. It covers the primary use case, parameter roles, return fields, latency, cost, and clear routing to alternatives. There is no critical gap that would prevent an agent from selecting and invoking the tool correctly. The only minor omission is error handling or rate limits, but given the tool's simplicity and the annotations, this is not a significant 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 description coverage is 100%, so all parameters are documented in the schema itself. The description adds contextual meaning by explaining that query is required, text includes source text, and outputSchema shapes a structured reply, tying them to the tool's purpose. However, it does not elaborate on the type enum values or the structure of outputSchema beyond that, so while it adds value, it does not fully compensate for what the schema already covers. A score of 4 reflects that it goes beyond a simple repetition but stops short of deep parameter guidance.

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 clear, specific action: 'Ask a question and get a written answer with citations.' It distinguishes itself from siblings by naming post_exa_agent_runs, post_exa_search, and post_perplexity_sonar, and explains its position between search and research. An agent can immediately understand what this tool does and how it differs from related tools.

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 explicitly gives when-to-use and when-not-to-use guidance: it says this tool is 'faster and cheaper than post_exa_agent_runs' and 'more direct than reading post_exa_search results yourself.' It also names an alternative, post_perplexity_sonar, with a cost comparison and a condition to choose it ('reach for Exa when the retrieval needs to be semantic'). This leaves no ambiguity about selection criteria.

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?

Beyond the readOnly/idempotent annotations, the description adds valuable behavioral detail: caching behavior with fallback to live crawl, a statuses[] array for per-URL failures instead of exceptions, measured latency, and flat billing. This fully informs the agent of side effects and error handling.

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 front-loaded with the core purpose, then logically flows through parameters, output, error handling, performance, cost, and alternatives. Each sentence provides useful information without redundancy, though it is a bit dense and could be tightened.

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 an output schema present and six parameters, the description covers the essential operational context: return structure, per-URL error reporting, caching, latency, cost, and a clear alternative. Nothing critical is missing for an agent to use it correctly.

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 adds meaningful context for the ids parameter (it takes URLs from post_exa_search) and lists the toggles, going slightly beyond the schema by clarifying the ids relationship. It does not dive deep into each parameter, but the schema already handles that.

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 clearly states the tool fetches page text and metadata for URLs the agent already has, distinguishing it from search tools. It also names a specific sibling (post_firecrawl_crawl) for the whole-site case, making the purpose unambiguous.

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?

It explains that ids come from post_exa_search and points to post_firecrawl_crawl as an alternative for whole sites, giving clear context on when to use this tool. It does not explicitly enumerate exclusions against other extraction tools, but the guidance is sufficient for most scenarios.

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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds genuinely new behavioral context: results carry no page text by default, billing is a flat $0.08, measured latency is 1.4 seconds, and `id` is the URL to pass to post_exa_contents. No contradiction with annotations.

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 dense but well-organized: the semantic-search purpose comes first, followed by return shape, operational facts, and sibling routing. It is longer than minimal, but every sentence carries operationally useful information, including cost, latency, and downstream usage.

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 11-parameter search tool with a rich schema, output schema, and comprehensive annotations, the description covers behavior, return-value semantics, sibling selection, and operational constraints. Nothing material is missing for an agent to invoke it correctly or route to an alternative.

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 the input schema already documents all 11 parameters in detail. The description adds a helpful summary of the required `query` and the main narrowing parameters, but it introduces no meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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 ('Search') and resource ('the web'), then immediately clarifies the distinguishing approach ('by meaning rather than by keyword'). It also names sibling alternatives and differentiates itself from them, so an agent can tell it apart without inspecting other 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?

Explicitly states when to choose this tool over post_tavily_search (when the query is a description rather than keywords), and gives routing conditions for Tavily (want text in same call) and post_exa_answer (want a written answer). This is concrete, actionable guidance with named alternatives.

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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond that: the HTTP 202 submission semantics, the job envelope shape with output initially null, the terminal-state output being an array of markdown/metadata documents, and the idempotency behavior of re-submitting with the same key returning the original job. It does not contradict the annotations. It loses one point because it doesn't mention polling frequency or error/retry behavior, but the core async lifecycle is well disclosed.

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 dense but well-organized: it front-loads the core action and required fields, then the async behavior, then the polling instruction, then the when-to-use alternatives. Every sentence earns its place. It is slightly long, but the length is justified by the async lifecycle and routing guidance. It loses one point because the job-envelope field list is somewhat verbose and could be trimmed without losing meaning.

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 9-parameter async tool with a rich output schema, the description is complete: it covers required fields, async submission semantics, the polling endpoint, the terminal output shape, and the alternative tools. The output schema exists, so the description needn't explain return values in detail. An agent has everything needed to select and invoke this tool correctly.

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 the schema already documents all 9 parameters. The description adds a little by naming the tuning parameters and emphasizing that urls and Idempotency-Key are required, but it doesn't add meaning beyond the schema for individual parameters. Baseline 3 is appropriate when the schema carries the full parameter documentation burden.

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: 'Scrape many URLs as one background job.' It clearly distinguishes this from siblings by naming post_tavily_extract and post_firecrawl_scrape as alternatives for immediate or single-page needs. The async nature and job-envelope return are stated up front, so an agent can tell this tool apart from the synchronous scraping siblings without opening the 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?

The description gives explicit when-to-use guidance: 'Use it when you have a list of URLs and do not need them immediately.' It also names the alternatives and the conditions that select them: post_tavily_extract for a small synchronous batch, post_firecrawl_scrape for a single page. It even instructs to poll get_firecrawl_batch_scrape_job until terminal, which is the correct follow-up action.

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?

The description adds substantial behavior beyond the annotations: it reveals the async lifecycle (HTTP 202, job envelope with `id`/`status`/`pricing`, `output` null initially), the cost model (`pricing.billingMode` is `metered_result`, cost scales with what the crawl finds), and idempotency semantics (reusing an `Idempotency-Key` returns the earlier job). None of this is derivable from `readOnlyHint`/`openWorldHint`/`idempotentHint` alone, and it does not contradict any annotation.

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?

While long, the description is densely functional and every sentence earns its place: purpose first, then requirements, async flow, cost caveat, idempotency rule, and alternatives. The most decision-critical facts (required params, async nature, cost risk, when to use a sibling) are front-loaded, and there is no filler or restatement of what the input schema already says.

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 complex tool (14 parameters, nested objects, async job lifecycle), the description is complete: it covers the job envelope, output shape, polling statuses, the cost implications of the metered billing mode, the idempotency key requirement, and the correct alternative tools. The input schema covers parameter semantics and constraints, and the output schema exists for return values, so no essential guidance is left to inference.

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%, which sets the baseline at 3. The description adds meaning beyond the schema by flagging `limit` as a cost control ("cost scales with what it finds — set `limit`") and by grouping `includePaths`, `excludePaths`, `maxDiscoveryDepth`, `crawlEntireDomain`, and `allowSubdomains` as steering knobs, plus `delay` and `maxConcurrency`. It doesn't elaborate every parameter, but the schema already documents each one, so the added value pushes it a notch above baseline.

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 first sentence states a specific verb and resource — "Crawl a whole site rooted at `url`" — plus the expected outcome ("content of every page it keeps"). It also differentiates from siblings by naming `post_firecrawl_batch_scrape` (better for a handful of known URLs) and `post_firecrawl_map` (better for structure alone), so an agent can pick the right tool without opening other 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?

The description explicitly tells the agent when to use this tool versus alternatives: "For a handful of known URLs `post_firecrawl_batch_scrape` is cheaper, and for structure alone `post_firecrawl_map` costs far less." It also gives a concrete usage recipe (required `url`, `limit`, and `Idempotency-Key`; steering knobs like `includePaths` and `excludePaths`) and states the full polling lifecycle with the sibling to poll (`get_firecrawl_crawl_job`) and the terminal statuses to wait for.

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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint all safe, and the description adds valuable context: 'Measured at about 9 seconds,' 'Billed 1 credit per discovered link,' and 'Returns success, a request id, and links[] with url and title — note these are objects with a title, unlike post_tavily_map which returns bare strings.' It goes beyond the annotations by quantifying latency and billing, and highlighting a critical data format difference. Not a 5 because it doesn't mention pagination or rate limiting, but strong for annotation coverage.

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 tightly written, with each sentence earning its place: what it does, key requirements, return format, timing, billing, and alternatives. It front-loads the core purpose and requirements. No fluff.

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?

The tool is simple (2 params, no nested objects) and has rich annotations plus a fully covered schema. The description covers usage context, output format, performance, and cost. It also compares with siblings to prevent misuse. For this complexity, nothing critical 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 description coverage is 100%, so the schema already documents both parameters. The description adds that both are required (redundant with schema) and that limit is a cost control ('cost control, not just a page control'), which provides insight beyond the schema's 'Maximum number of links to discover.' This is useful, but since schema covers semantics, baseline 3 is appropriate.

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 clearly states the tool's purpose: 'List the URLs reachable from a starting page, without fetching any content.' This is specific and distinct from siblings like post_firecrawl_scrape (fetch content) and post_tavily_map (different format). The verb 'list' and resource 'URLs' are specific, and the exclusion of content fetching distinguishes it immediately.

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 explicitly says 'Use it to size a site before paying to crawl it, then fetch only what matters with post_firecrawl_scrape,' and contrasts with 'post_firecrawl_crawl' for content and structure in one pass. It also notes the cost control aspect. This gives clear guidance on when to use and when to prefer alternatives.

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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond these: it states a ~10 second latency, that HTTPS is required and PDFs are rejected (hard errors), and details the response structure (success, data.markdown, large metadata with og/twitter tags, statusCode, sourceURL, language). No contradiction with annotations.

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 front-loaded with the core action, then requirements, output shape, timing, constraints, and usage guidance. It is a little long but every sentence adds value, and the structure is logical. No fluff or repetition that doesn't earn its place.

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 tool has only 3 parameters and an output schema exists, the description fully covers what an agent needs to call it correctly: required fields, constraints, expected response, latency, and when to use alternatives. Nothing essential 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?

The input schema already covers all three parameters with descriptions and examples (100% coverage). The description adds extra constraints: url must be HTTPS and not a PDF, proxy must be explicitly set to 'basic' on the metered profile, and formats must be exactly ['markdown'] when present. This enriches the schema meaning, though the schema already carried most of the burden.

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: 'Fetch one URL and get its main content back as markdown.' It immediately differentiates from siblings by naming the batch scraper, the Tavily extractor, and the map tool, so an agent can tell exactly when this tool is the right one.

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 guidance is provided: 'Use it when you have the URL and want the text.' It then contrasts with alternatives: for multiple URLs use post_firecrawl_batch_scrape or post_tavily_extract, and to discover URLs first use post_firecrawl_map. This is textbook usage guidance.

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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it discloses the return shape (success, creditsUsed, id, data.web[]), the limitation to titles/snippets, measured latency (~15s for 2 results, slowest of search tools), and billing behavior (ceil(limit/10)*2 credits). It also discloses rejection of unsupported modes. This is rich, non-redundant behavioral disclosure.

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 dense but well-organized: it front-loads the core purpose and return shape, then adds performance, billing, and routing guidance. Every sentence earns its place, though the length is substantial. The structure is logical and scannable, with the alternative routing at the end. Slightly long but not bloated.

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 tool's complexity (2 params, output schema present, annotations covering safety), the description is complete. It covers return format, performance, billing, platform constraints, and alternatives. The output schema already documents the response structure, so the description doesn't need to repeat it. Nothing an agent needs to decide whether to call this tool 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 description coverage is 100%, so the schema already documents both parameters. The description adds meaning by explaining the billing implication of limit (ceil(limit/10)*2 credits) and the latency implication, which goes beyond the schema's 'Maximum number of results to return.' It also clarifies that query is required and that limit controls result count, but the schema already covers that. The added cost/latency context justifies a 4 rather than 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?

The description opens with a specific verb and resource ('Search the web and get back ranked results') and immediately distinguishes itself from sibling search tools by naming alternatives and their conditions. It clearly states what the tool returns (titles and snippets only, no page text), which differentiates it from post_tavily_search, post_exa_search, and post_firecrawl_scrape.

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 provides explicit when-to-use and when-not-to-use guidance: it names post_tavily_search for page text in the same call, post_firecrawl_scrape for known URLs, and post_exa_search for meaning-based relevance. It also states platform constraints (AIsa metered profile supports only web source; scrapeOptions, enterprise mode, non-web sources rejected). This is exemplary routing guidance.

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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description is not required to repeat those. Instead it discloses crucial behavioral details: server-pinned model and tool, per-request search cap, output structure with web_search_call and message items, and exact billing formula. This is rich, non-redundant behavioral context that materially affects whether an agent calls the tool and how it interprets results.

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?

Although the description is long, every sentence earns its place. The core purpose and usage guidance are front-loaded, followed by billing and output details. There is no fluff or redundancy; each clause adds value, from the server-controlled cap to the cost formula. It is well-structured and information-dense without being bloated.

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?

The tool is moderately complex (search + model + billing + output structure), but the description covers all critical aspects: how the search is performed, what the output looks like, how billing works, and how it differs from alternatives. An output schema exists, so the description does not need to enumerate every field, but it explains the high-level output shape. For an agent to call this correctly and interpret the response, nothing essential 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%, so the description does not need to re-explain each parameter. It adds a minor clarification that `input` can be a message array and that the format matches the OpenAI Responses API, which is useful but not transformative. The baseline of 3 is appropriate; the schema already documents the parameters fully, and the description offers only a small amount of extra context.

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 clear, specific verb and resource: 'Ask a question and get an answer that an OpenAI model wrote after searching the live web.' It explicitly names two sibling tools and how they differ, so an agent can immediately distinguish it from post_anthropic_websearch_search (Anthropic model) and post_tavily_search (raw links). This exceeds a mere statement of function by providing differentiation.

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?

It gives an explicit when-to-use rule: 'Use this when you want a written, cited answer grounded in current web content from an OpenAI model.' It also names alternatives and directs the agent to them for other use cases. This is exemplary guidance that removes any guesswork about tool selection.

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 declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds significant behavioral context beyond these: cost per successful result ($0.001), non-billing on certain error codes, typical latency (4–8s), the passthrough nature of the request body, and the returned content (AI answer text and cited URLs). It also discloses the 422 error for unsupported sources, all of which materially affect how an agent should use the 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?

The description is compact but information-dense: it opens with the core purpose and endpoint, then covers required fields, pricing, latency, error behavior, and explicit alternatives in a logical flow. Every sentence carries unique value, and the exclusion of LLM sources is front-loaded so the agent doesn't have to read far to avoid a wrong call.

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 this complexity—passthrough behavior, cost, latency, error handling, and a clear sibling alternative—the description covers all essential aspects an agent needs to call it correctly and safely. It also references the output (AI answer text and cited URLs), and with an output schema present, the agent has complete information to integrate 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 coverage is 100% so the baseline is 3, but the description adds value by prescribing how to combine parameters ('Send query with render: "html", parse: true, and a country-level geo_location') and by explaining the meaning of the source values. While the schema already documents each parameter, the description gives practical usage guidance that clarifies expected values and their interplay.

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 verb ('query'), a precise resource (Google AI answer engines: AI Overviews and AI Mode), and the exact upstream endpoint. It clearly distinguishes this tool from the related LLM tools by explicitly naming post_oxylabs_llm and get_oxylabs_llm_job as the correct alternatives, so an agent can immediately tell what this tool is for.

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 provides explicit when-to-use and when-not-to-use guidance: it states that LLM sources are no longer served and instructs to use post_oxylabs_llm instead, including the exact HTTP 422 error that will be returned if misused. It also gives operational guidance on required fields (render, parse, geo_location) and a minimum client timeout of 30s based on expected latency, leaving no ambiguity about when and how to invoke 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?

Despite annotations indicating a destructive, non-read-only open-world operation, the description adds valuable detail: submission returns HTTP 202, output is null initially, billing is $0.00145 per successful fixed_request job, and failed/cancelled jobs are not billed. It also explains the Idempotency-Key replay behavior, going well beyond the annotations.

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 dense but purposeful, front-loading the core async submission concept before covering response, billing, cancellation, and sibling routing. It is slightly long as a single paragraph and repeats the Idempotency-Key advice, but every sentence contributes actionable information.

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 9 parameters, nested objects, an output schema, and async, billed behavior, the description is admirably complete. It covers required inputs, polling, cancellation, billing exceptions, and how to route synchronous Google sources to a different sibling tool, leaving no critical 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 re-emphasizes that `source` selects the engine, `prompt` is required, and `Idempotency-Key` must be unique, but it does not add new param-level information beyond what the schema already provides.

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 'Submit an asynchronous query to a major LLM answer engine — ChatGPT, Gemini, or Perplexity — via Oxylabs Push-Pull,' naming a specific verb, resource, and scope. It also distinguishes itself from siblings by stating that Google sources belong on post_oxylabs_ai_search and that results are polled via get_oxylabs_llm_job.

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 explicit when-to-use context: these sources take ~40–90s and run as background jobs, so polling get_oxylabs_llm_job is required. It also flags the alternative for synchronous Google sources ('stay on post_oxylabs_ai_search') and points to the cancel endpoint for queued jobs.

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?

Beyond the destructiveHint annotation, the description discloses concrete effects: it releases the authorized hold, never bills a cancelled job, returns status: cancelled, and cannot operate on terminal jobs. This is exactly the operational context an agent needs before invoking a mutation.

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 tight sentences carry the action, the precondition, the result, and the billing outcome with no redundancy. The most decision-relevant information is front-loaded.

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 cancellation tool, the description covers the success condition, the failure condition, the return envelope, and the financial consequence. With an output schema present, nothing essential 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%, so the jobId parameter is already documented as 'The job id returned by the submit call.' The description reinforces this by referencing jobId and the submit tool, but adds no new semantic detail 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 uses a specific verb and resource: cancel an Oxylabs LLM job, scoped to queued jobs and addressed by jobId. This clearly distinguishes it from the sibling submit tool post_oxylabs_llm and the retrieval tool get_oxylabs_llm_job.

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 states when the tool applies (queued jobs submitted by post_oxylabs_llm) and when it does not (jobs already in a terminal state). It doesn't name an alternative tool for checking status, but the boundary conditions are explicit enough for correct selection.

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?

The annotations already cover readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral context: response shape ('choices[0].message.content', 'citations', 'search_results[]', 'usage'), latency ('Measured at about 3 seconds'), and flat pricing ('$0.012 per request'). No contradiction with annotations exists.

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 dense but logically organized, front-loading purpose, payload, output, and then adding cost, latency, and sibling routing. Minor redundancy keeps it from a perfect score: 'cheapest and fastest' restates the preceding timing and billing details.

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 13 parameters, rich annotations, an output schema, and a large sibling family, the description covers all operational essentials: exact payload requirement, return contract, cost, latency, and when to choose each relevant sibling. The schema handles remaining parameter details.

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 a critical clarification: 'model (required, `sonar`)', narrowing the schema's wide enum to the intended value for this specific endpoint. It also explains the body shape and return structure. Minor tension: the schema's model enum includes sonar-pro, sonar-reasoning-pro, and sonar-deep-research, while the description routes those to sibling tools, which could confuse a literal reading.

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 verb-resource combination: 'Ask a question and get a written answer with web citations,' and distinguishes it from link-list tools with 'rather than a list of links to read yourself.' It clearly identifies the Perplexity Sonar endpoint, matching the tool name and title.

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?

It explicitly states when to use the tool: 'use it for a single factual question,' and names alternatives with explicit conditions: 'Step up to post_perplexity_sonar_pro for multi-part questions, or ... reasoning_pro when the answer requires working through steps. If you need results you can iterate over ... use post_tavily_search; post_exa_answer answers the same shape...' This is exemplary routing guidance.

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?

The description goes well beyond the annotations by disclosing the extreme latency and response size ('a two-sentence question measured 192 seconds and returned 86 KB after 10 upstream searches'), the timeout risk ('Many clients time out well before it answers'), and the flat pricing. It also warns against looping, which is critical behavioral context for an agent deciding whether to call this 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?

The description is dense but every sentence earns its place: the core purpose, the required model, the output shape, the performance warning with concrete numbers, and the routing guidance. The warning is front-loaded after the purpose, and the sibling comparison closes it efficiently.

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 complex, slow, report-generating tool with an output schema and full parameter documentation, the description covers everything an agent needs: what it returns, how long it takes, when to use it, and when not to. The output schema handles return-value details, so nothing critical 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 description coverage is 100%, so the schema already documents all 13 parameters. The description adds the required model value ('sonar-deep-research') and names the output fields, but it doesn't add new meaning to individual parameters beyond what the schema provides. Baseline 3 is appropriate.

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 ('Commission a report: this endpoint runs many searches and writes a long, cited document'), which clearly distinguishes it from the other Perplexity endpoints. It also names the required model and the key output fields, so an agent can tell this is the deep-research report generator among the sibling tools.

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 explicit when-to-use guidance: 'call it only when a report is genuinely the deliverable, and never in a loop.' It also contrasts with the sibling endpoints ('For anything you would read in one sitting, the other three Perplexity endpoints answer in seconds'), which is exactly the kind of alternative routing an agent needs.

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 declare the tool read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds behavioural context beyond annotations: latency (~10s), cost ($0.012 flat), the fact it performs more than one search pass, and the response shape. It also notes performance relative to `sonar` (three times slower) which is not in structured data.

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 concise sentences, each carrying essential information: purpose, performance/relationship to sibling, and selection criteria. It is front-loaded with the outcome ('written answer with citations') and avoids repetition of schema details.

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 13-parameter tool with complete schema coverage and output schema, the description covers the key selection criteria, behavioral expectations, performance, and cost. It also routes the agent to the correct sibling tool. Minor gaps such as streaming or filtering parameters are already documented in the schema, so the description is sufficient.

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 baseline is 3. The description adds specific guidance that `model` is required and expected to be `sonar-pro`, and that `messages` is the input, which pins down the primary parameter beyond the generic enum. This adds value above 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 states the tool performs a multi-pass search and returns a written answer with citations. It explicitly differentiates from siblings by naming `post_perplexity_sonar` for single lookups and `post_perplexity_sonar_reasoning_pro` for reasoning-heavy questions. This is a specific verb+resource statement with clear sibling differentiation.

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?

It explicitly says 'Use it for questions with several parts or follow-ups' and contrasts with `sonar` for single lookups and `sonar_reasoning_pro` for reasoning, giving clear when-to-use and when-not-to-use guidance. It also notes the same request/response shape as `sonar`, which helps agents migrate.

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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it discloses the response shape ('`choices[0].message.content`, `citations`, `search_results[]` and `usage` out'), the measured latency ('about 5 seconds'), and the flat pricing ('$0.012 per request'). It also clarifies the reasoning behavior ('step-by-step answer backed by web search'). The only minor gap is that it doesn't mention streaming behavior, but the schema covers `stream`.

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 three sentences with zero waste. The first sentence front-loads the core purpose and behavior, the second adds the response shape and cost/latency, and the third routes to alternatives. Every sentence earns its place.

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 13-parameter tool with 100% schema coverage, an output schema, and rich annotations, the description is complete. It covers what the tool does, when to use it, what comes back, and how it differs from siblings. An agent has everything it needs to select and invoke this tool correctly.

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 the schema already documents all 13 parameters. The description adds the key semantic constraint that `model` is required and should be `sonar-reasoning-pro`, and it names the output fields. However, it doesn't add meaning to parameters like `search_context`, `top_k`, or `temperature` beyond what the schema already provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Ask a question that has to be worked through') and a clear resource ('Sonar Reasoning Pro'), and immediately distinguishes it from siblings by naming the faster `post_perplexity_sonar` and the longer `post_perplexity_sonar_deep_research`. The phrase 'chain-of-thought reasoning with search' in the title is reinforced by the description's focus on step-by-step answers backed by web search.

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 explicitly states when to use this tool: 'Use it for comparison, causation and analysis.' It also gives exclusions: 'When the question is simply what is the case, `post_perplexity_sonar` is faster; when you need a long report over many sources rather than an answer, `post_perplexity_sonar_deep_research`.' This is a textbook example of when/when-not guidance with named alternatives.

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 mark the tool as read-only and idempotent, and the description adds substantial behavioral context: it requires a JSON body, returns a `{"message": "…"}` JSON object, is about 2 KB, and that streaming modes repeat the whole answer in every event, measured at 177 KB. This goes well beyond what annotations or schema convey.

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 dense but every sentence earns its place: differentiation from siblings, JSON body requirement, parameter values, mandatory response mode, return format, size, streaming caveat, and the tool's limitation. The most important guidance is front-loaded in the first sentence and the warning is placed prominently.

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 4-parameter tool with full schema coverage, the description is complete: it explains what the tool does, how to obtain the required ID, how to invoke it safely, what the output looks like, and what it cannot do. There are no critical gaps an agent would need to guess at.

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 adds meaningful value by clarifying that `search_id` must come from a prior search call and by warning that `response_mode` should be NON_STREAMING with quantitative evidence. It does not add much beyond the schema for `language` and `detail_level`, but the critical parameter guidance is present.

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 verb and resource: 'Explain a result set you already fetched.' It clearly distinguishes this tool from the search endpoints by name ('Unlike the three search endpoints') and explicitly states it 'cannot run one.' An agent can immediately tell what this tool does and what it is not for.

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 direct guidance: use `response_mode: NON_STREAMING`, explains why COMPLETE/INCREMENTAL modes are impractical ('a tool call cannot consume a stream incrementally anyway'), and clarifies the tool only explains existing searches, not runs them. It also names the exact search endpoints that produce the required `search_id`. This is explicit and actionable.

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 mark this as read-only and non-destructive, and the description adds valuable behavioral context beyond that: result entry shape varies by source, academic fields like authors and citations are optional, latency is about 3 seconds, and the returned id should be kept for a related tool. There is no contradiction with annotations.

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 most important purpose and usage guidance are front-loaded, followed by return-shape warnings and routing advice. It is somewhat dense and includes an extra latency estimate, but every sentence still contributes useful selection or invocation information.

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?

The description covers what the tool returns, how the result shape varies, which siblings to prefer in which situation, and how the returned id should be used. With an output schema present and annotations covering safety, nothing call-critical 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%, so the schema already documents each parameter with descriptions and constraints. The description adds the transport detail that parameters go in the query string and flags query as required, which is useful but only modest extra 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 clearly states it searches web and academic sources together and is aimed at questions straddling both domains. It names the specific resource and distinguishes itself from sibling tools like post_scholar_search_web and post_scholar_search_scholar.

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?

It explicitly says to use this tool when you do not know in advance which source kind will answer, and directs users to the more predictable single-source siblings when they do know. This gives clear when-to-use and alternative routing guidance.

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 establish the read-only/idempotent profile; the description adds the important query-string-not-body constraint and a performance estimate. It also points out that `number_of_citations` is unavailable from general web search, though the raw return shape is already present in the output schema.

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 dense but front-loaded with the core purpose and then proceeds logically through request format, return values, and usage guidance. Some extras such as 'Measured at under 2 seconds' are marginal, so it is not maximally lean.

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?

Covers the main invocation details, return highlights, and routing to related tools, and the output schema fills in the full response structure. It is slightly incomplete by not distinguishing from `post_scholar_search_web`, but overall the agent has what it needs to select and call this tool correctly.

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 description mostly restates parameter names and constraints already in the schema. It adds little beyond noting that parameters go in the query string, which is a transport detail rather than new semantic meaning for individual parameters.

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 'Search academic literature' and goes on to specify the distinguishing value (peer-reviewed sources, citation counts). It also names sibling tools for different cases, making the tool's purpose unmistakable.

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?

Explicitly says to use it when peer-reviewed sources or citation counts matter and names `post_tavily_search` for current events/product pages, plus `post_scholar_search_mixed` and `post_scholar_search_explain`. However, it does not address the closely named sibling `post_scholar_search_web`, so the routing guidance is slightly incomplete.

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 declare readOnly, idempotent, non-destructive. The description adds critical behavior beyond that: parameters go in the query string despite POST, JSON body not accepted, response includes `id` and `results[]` with only title/link/snippet, measured latency and size, and that no page text is returned. No contradiction with annotations.

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 dense but every sentence carries information: purpose, warning about transport, response shape, latency, use-case fit, and relationship to siblings. It is front-loaded with the core action and well-organized with the emoji warning and bolded key terms. No wasted words.

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 a non-standard transport method and specific output limitations, the description covers everything an agent needs: how to call, what is returned, what is not returned, and what to do with the returned `id`. Output schema exists, but the description still adds necessary context about the query string and response brevity. It is complete for correct invocation.

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 the important fact that parameters must go in the query string, not a JSON body, which is not in the schema. It also restates defaults and range limits but the query-string note is genuinely additional semantic value.

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 verb ('Search'), a resource ('the open web'), and characterizes the result as a 'lean result list.' It distinguishes from siblings by noting it returns only title/link/snippet and contrasts with post_tavily_search for content, making its role clear.

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?

It explicitly states when to use it: 'suits an agent that only needs to know what exists.' It also names the alternative (post_tavily_search) for when content is needed, and instructs to keep the `id` for post_scholar_search_explain. This is explicit when/when-not guidance.

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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond those: it notes the synchronous nature ('It answers synchronously, which post_firecrawl_crawl does not') and provides a measured performance estimate ('about 4.5 seconds for a 3-page limit') plus a warning that cost/time grow with bounds. This is meaningful additional disclosure, though not exhaustive (no error behavior or rate limits mentioned).

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 a compact paragraph of about five sentences that front-loads the main action and then layers in constraints, performance, and alternatives. It is appropriately sized for a tool with 17 parameters and conveys high signal per sentence. 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 tool's complexity (17 params, multiple sibling tools), the description is exceptionally complete. It covers the core operation, use cases, performance expectations, cost implications, and clear routing to alternatives. The output schema exists, so return values are already documented, and the description doesn't need to repeat them. An agent has everything needed to decide whether and how to call 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?

The schema covers 100% of parameters, so the baseline is 3. The description adds conceptual value by grouping key parameters ('Steer it with natural-language instructions plus regex path and domain filters, and bound it with max_depth, max_breadth and limit') and by describing the return structure ('Returns base_url and results[] with url and raw_content'), which goes beyond the schema's isolated field descriptions. It doesn't explain each parameter in depth but provides a useful high-level model.

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: 'Walk a site from a root url and return the content of the pages it finds.' It clearly states the core function and immediately distinguishes itself from sibling tools by naming post_firecrawl_crawl, post_tavily_extract, and post_tavily_map, so an agent can tell them apart 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 guidance on when to use it: 'Use it for broad coverage of one site — documentation, a catalogue, a competitor's blog.' It also contrasts with alternatives: post_firecrawl_crawl for background/large crawls, post_tavily_extract for a handful of known pages, and post_tavily_map for sizing a site. This gives clear selection criteria and exclusions.

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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that failed fetches appear in failed_results[] rather than raising an error, warns the agent to read that array, and provides measured latency. This is meaningful behavioral context an agent needs before calling.

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 front-loads the core purpose, then uses bolded array names and short clauses to cover return behavior, failure handling, performance, and sibling alternatives. Every clause earns its place with 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 read-only extraction tool with a rich output schema, the description provides purpose, response shape, failure semantics, performance expectation, and sibling routing. Nothing needed for correct invocation 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%, so the baseline is 3. The description restates that urls is required and can take several URLs, and points to format and extract_depth, but it does not add much semantic detail beyond the schema's already complete parameter descriptions.

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 explicitly says it fetches clean, parsed content for URLs you already have, naming the specific resource and use case. It is immediately distinguishable from post_tavily_search, post_tavily_map, and post_firecrawl_batch_scrape.

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?

It gives a clear when-to-use rule ('whenever you can already name the pages'), an explicit alternative to avoid (post_tavily_search), and concrete handoffs to post_firecrawl_batch_scrape for long lists and post_tavily_map for site discovery. This fully routes an agent among siblings.

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 signal a safe, read-only, idempotent operation; the description adds valuable behavioral detail: no page content is fetched, the result is a flat array of URL strings rather than objects, and it returns `response_time`/`request_id`. It also gives a measured latency of about 1.5 seconds. It does not discuss external-domain inclusion in prose, though the schema covers this.

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 front-loaded with the core purpose inclue first sentence, then covers controls, return shape, performance, and sibling routing in compact sentences. Every sentence earns its place; there is no filler or repetition.

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 12-parameter tool with full schema coverageizing and an output schema, the description supplies the missing conceptual context: what the tool returns, how it behaves, and when to prefer it over its siblings. Nothing essential for correct selection or invocation is left out.

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 the schema already documents all 12 parameters. The description highlights the most consequential controls (`url`, `instructions`, and the regex path/domain filters) but adds little meaning beyond what the schema already states. That meets the baseline for high schema coverage without exceeding it.

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: 'List a site's URLs from a root `url`'. It clearly distinguishes itself from siblings by stating it does not fetch page content and by naming `post_tavily_extract` and `post_tavily_crawl` as the content-oriented alternatives.

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?

Usage context is explicit: use this tool to 'size a site before committing to a crawl', then use `post_tavily_extract` for targeted content. It also tells the agent that `post_tavily_crawl` is the right choice when content and shape are needed in one call, leaving no ambiguity.

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 declare readOnly, idempotent, and openWorld hints, but the description adds valuable behavioral context beyond them: it returns extracted text (eliminating a second call), measures roughly 6 seconds for 2 results, and trades cost against depth via search_depth. It does not contradict annotations.

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 dense but well-organized: it front-loads the core value (extracted text, no second call), then summarizes response shape, filtering options, and ends with clear alternative routing. Every sentence earns its place; 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?

For a 19-parameter tool with a full output schema and rich annotations, the description covers the key behavior, performance, and selection criteria. It does not need to repeat the schema, and it addresses all critical decision points an agent needs to invoke it correctly.

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 adds extra semantic value by explaining that include_answer yields a one-paragraph answer, that start_date/end_date and time_range filter by publish date, and that search_depth trades cost against depth. These hints go beyond the schema's field descriptions.

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 verb-resource pair ('Search the web') and immediately distinguishes this tool from siblings by noting it is the only one that returns ranked results and page text in one call. It explicitly says it extracts page content so no second fetch is needed, making its purpose unambiguous.

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?

It explicitly designates this as the default choice for open-web research and provides precise conditions for when to use alternatives: post_tavily_extract for known URLs, post_exa_search for semantic matching, post_perplexity_sonar for written answers, and post_scholar_search_scholar for papers. This is clear when-to-use and when-not-to-use guidance.

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?

The description discloses meaningful behavior beyond annotations: search spans the entire AIsa catalogue, candidates may belong to modules other than the current one, multiple providers for the same metric are surfaced, and no API key is required. This gives the agent a clear picture of scope and output behavior.

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 front-loaded with the core purpose and is dense with useful information: scope, no-auth requirement, response shape, and relationship to the catalogue. Each sentence adds operational value, and the structure makes the tool's behavior predictable.

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 complex discovery tool with output schema, the description is unusually complete: it explains the response modalities, candidate fields, direct pass-through to `use`, full-catalogue search behavior, and cross-provider visibility. An agent has enough context to invoke and interpret the tool correctly.

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 schema already documents all parameters. The description adds value by explaining that the category parameter is not a hard boundary—search spans the full catalogue—and that queries are plain-language task descriptions, which clarifies how to use the tool effectively.

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 clearly states the tool finds AIsa data operations across many categories via a plain-language query. It distinguishes itself from siblings like get_details and use by emphasizing that search covers the full catalogue, not just the pinned category.

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 conveys when to use search: when you need to discover operations across the full catalogue, even those not in the current tools/list. It also implicitly contrasts with get_details by noting that returned candidates already include input_schema, so they can be passed directly to `use` without an extra call.

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 provide readOnly=false, openWorldHint=true, and destructiveHint=true. The description adds valuable behavior beyond that: billing per call, the BatchCallResult response shape, and the error structure with retryable status. It does not spell out side effects, but the destructive flag is already carried by annotations, so the additional context is sufficient.

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 short sentences, each earning its place: purpose, cost, response shape, and routing guidance. Key behavioral facts are front-loaded, and nothing is redundant with the schema or annotations.

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 that an output schema exists and all parameters have descriptions, the tool description is complete enough for correct invocation. It covers cost, return/error contracts, and how routing to this tool differs from calling pinned tools directly, leaving no practical 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 description coverage is 100%, and each parameter is already clearly documented: operation_id as returned by search, search_id provenance, arguments matching input_schema, and max_price_usd as a spend guard. The description does not need to add parameter detail, so baseline 3 is appropriate.

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 'Execute one AIsa operation,' a specific verb+resource statement. The word 'one' distinguishes it from the sibling batch_use, and the closing note distinguishes it from calling pinned tools directly. An agent can tell what this tool is for immediately.

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?

It explicitly states when to use the tool: 'this is the way to call anything found through search.' It also gives the alternative: 'Pinned tools in tools/list can also be called directly.' This is clear when-versus-alternative guidance with no ambiguity.

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