AIsa Web Search & Research

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

Adds substantial context beyond the readOnlyHint/openWorldHint/destructiveHint annotations: the call is free, it requires the Authorization header, and it discloses result semantics ('ok is true only when the balance was read; otherwise each entry of errors says what to do in next_step'). That tells an agent how to interpret partial failure, which annotations cannot 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?

Three sentences, front-loaded with what the agent gets, followed by cost/auth, then call triggers, then result interpretation. No sentence is redundant and none could be dropped without losing 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 zero-parameter read tool with an output schema already present, the description covers the remaining gaps: cost, auth requirement, invocation triggers, and the ok/errors/next_step contract. Nothing an agent needs to call or interpret it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the description has nothing parameter-level to compensate for, and the schema is fully covered. A 4 rather than 5 reflects that it adds no input-syntax detail, though none is possible here.

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 concrete resource set (identity/key, account balance, Go-to-Market wallet, usage over 1/7/30 days) rather than restating the name. It is clearly distinguishable from every sibling, which are all Reddit, batch, or search tools. An agent knows exactly what it will learn by calling it.

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 triggering conditions are given: 'Call it to verify a new connection or to explain a 402.' That is a strong when-to-use statement. It stops short of 5 because it names no alternative tool or a when-not condition, though the sibling list offers no obvious competing diagnostic.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is not required to restate it. It adds genuine operational context: the batch_use prohibition, exact-name/prefix requirements, and session reuse semantics. It does not cover failure handling when names are invalid, keeping it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and size limit, and every sentence carries workflow value. The session_id sentence duplicates the schema's own parameter description, which is minor redundancy rather than bloat.

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 batch retrieval tool with an output schema, the description supplies the orchestration context an agent needs (source of names, next steps, session handling) without needing to explain return values. Nothing essential to 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 description coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema by constraining names to those returned by search and warning against a client prefix such as mcp__aisa__, which is not encoded in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Retrieve schemas for 1 to 20 exact tool names') and pins the source of those names to search. This clearly separates it from siblings like search (finds tools), batch_quote, and batch_use.

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 sequences the workflow: build arguments from successful schemas, then call batch_quote, and 'Do not call batch_use yet.' This is an explicit when-to-use and when-not-to-use instruction naming the alternative 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?

Goes well past the readOnly/idempotent annotations by explaining that quotes are price observations rather than authorization grants, and precisely delimiting what auto_execute_eligible does and does not waive (user prohibition, narrower scope, tighter budget). It also guarantees no execution fallback, which is the key behavioral risk for 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?

Purpose is front-loaded and most sentences carry distinct rules (no fallback, eligibility limits, naming, session reuse). It is on the long side and the argument-shape constraint is stated twice in spirit, but little is truly 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?

An output schema exists, so return-value documentation isn't required, yet the description still flags the two response fields that matter for a downstream decision. Combined with session and naming guidance, an agent has everything needed 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?

At 67% schema coverage the schema already documents each parameter, so the description earns credit only for added meaning: exact-name rules for 'tool', session_id reuse semantics, and the 1-to-20 argument-shape parallel with batch_use. It doesn't clarify search_id beyond what the schema states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Obtain AIsaServices cost quotes for 1 to 20 published tools') plus the crucial scope qualifier 'without executing them.' It is immediately distinguishable from the sibling batch_use, which executes rather than quotes.

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 names the parallel sibling ('Same input as batch_use') and draws the boundary ('Never falls back to execution'). It also gives operational conditions: use names exactly as search returns them, strip any mcp__aisa__ prefix, and reuse session_id from Search for the task.

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 mutability, destructiveness, and open-world behavior. The description adds critical business logic: billable calls, quote dependency, the meaning of auto_execute_eligible (waives only cost confirmation, not user prohibitions), and no silent retry. It doesn't detail rate limits or return format, but with an output schema present, that's acceptable.

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 and front-loads the cost warning, but it packs many separate instructions into one block, making it less scannable. Some sentences like 'A missing or failed quote is not free' add value, but the overall flow could be better 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?

Given the destructive, open-world annotations and the presence of an output schema, the description covers the essential preconditions and behavioral constraints. It could mention error handling or partial failure behavior, but the core guidance is sufficient 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 67%, and the description adds important semantics: tool names must be exact without client prefix, session_id reuse guidance, and 1-20 call limit. It doesn't explain search_id, but the schema description for search_id is already clear enough.

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 verb and resource: 'Execute 1 to 20 independent published-tool calls', and the title matches. It distinguishes itself from batch_quote by requiring a quote first, but doesn't explicitly contrast with the singular 'use' sibling, though that's implied by 'batch'.

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 and when-not-to-use conditions: only after a successful batch_quote with auto_execute_eligible=true or explicit user authorization. It also states re-quote conditions and prohibits silent retries, leaving little 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 cover the safety profile (readOnly, idempotent, non-destructive). The description adds genuine but cryptic behavior: 'Owner-scoped', reads/cancellation surviving admission disable, and access-policy gating. These are beyond the annotations, but they are vague policy statements rather than actionable behavior for a single-run fetch.

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?

Brief but poorly front-loaded: the opening sentence names a 'lifecycle' rather than the operation, and the tool embeds an irrelevant pricing boilerplate block that consumes space without helping an agent call the tool.

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?

An output schema exists, so return values need not be explained. However, for a simple get-by-id tool the description still omits the core operation, any hint about jobId, and any usage context, leaving the definition materially incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description says nothing about jobId — not its format, where it comes from, or whether it is owner-scoped/URL-safe. With only one parameter and zero documentation anywhere, the description fails to compensate for the coverage 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 never states the operation. It talks abstractly about 'local asynchronous job lifecycle' and admission policy, but never says it retrieves the details/status of a specific Exa agent run identified by jobId. The title ('Exa Agent Runs detail') carries more purpose than the prose, and an agent cannot distinguish this from sibling getters like get_exa_apis_v1_exa_agent_runs or 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?

No when-to-use guidance and no mention of alternatives. With ~37 siblings including several job-detail getters and a cancel endpoint, the description offers nothing to route the agent between reading a run, listing runs, or cancelling one.

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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds 'owner-scoped' scoping and notes access-policy/runtime constraints, which is some useful context beyond the annotations, but it is vague and partly obscured by unrelated admission-control wording.

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 opening sentence is abstract and not front-loaded with the core action, and the definition is padded with an unrelated aisa-pricing boilerplate block that adds no operational value for an agent trying to call the tool.

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?

An output schema exists, so return values need not be described. However, for a filtering/paginating list endpoint the description never says what is listed or how limit/cursor/status behave, leaving the call semantics under-specified.

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 only 33% and the description mentions none of the three parameters (limit, cursor, status). With low coverage the description should compensate by explaining filtering/pagination semantics, but it adds nothing.

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 reads 'Owner-scoped local asynchronous job lifecycle' – an abstract phrase that never states the actual verb+resource (listing agent runs). Only the title/name imply a list operation. It does not distinguish itself from the singular sibling get_exa_agent_run.

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?

There is no when-to-use guidance or routing to alternatives such as get_exa_agent_run (single run) or post_exa_agent_runs (create). The sentence about 'disabling new admission' concerns system behavior, not when an agent should select this tool.

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, open-world. The description adds little beyond a note that disabling admission doesn't stop reads, which is marginal. It doesn't say what the detail response contains or whether it's eventually consistent.

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 pricing block and lifecycle caveats are front-loaded boilerplate that bury the actual purpose. No clear leading sentence identifies the tool's function.

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 though an output schema exists, the description never says this returns batch scrape job status, leaves the jobId source unclear, and wastes space on unrelated pricing text. Key context for calling correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the single jobId parameter is an unlabeled string. The description gives no meaning, format, or source for jobId, so an agent must guess where the identifier comes from.

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 says 'Owner-scoped local asynchronous job lifecycle' but never states that this tool retrieves the status/detail of a Firecrawl batch scrape job. The name is essentially restated as abstract jargon rather than a specific verb+resource, so an agent can't tell what the tool returns.

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?

There is no indication of when to use this instead of siblings like get_firecrawl_crawl_job or post_firecrawl_batch_scrape. The admission-disable sentence is about lifecycle semantics, not 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, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds only vague context ('owner-scoped', 'access policy also apply') and includes irrelevant pricing boilerplate, without useful behavioral details like status response contents or authentication requirements.

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 text is short but not front-loaded with the tool's actual function, and it includes an irrelevant pricing HTML block that is pure noise. The opening sentence fragment is ambiguous and does not 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?

An output schema exists, so return values need not be described, and annotations cover safety. However, for a low-complexity detail tool the description still fails to establish the tool's core purpose or when to use it, leaving a significant contextual 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 0% and the description never mentions jobId or explains its expected format or source. The description therefore adds no semantic meaning beyond the bare parameter name in 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 'Owner-scoped local asynchronous job lifecycle' is a vague fragment rather than a specific verb+resource; it never states that the tool retrieves a Firecrawl crawl job by ID. The title 'Firecrawl Crawl detail' helps only marginally and is not reinforced by the description, leaving sibling confusion with post_firecrawl_crawl and get_firecrawl_batch_scrape_job unresolved.

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 provides policy statements such as 'Disabling new admission does not disable existing job reads or cancellation' and 'Runtime availability and access policy also apply,' but these are not when-to-use guidance. There is no explicit comparison to alternatives or instruction on when an agent should call this versus other crawl/job tools.

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 that this is a safe, read-only, closed-world operation. The description adds useful context beyond annotations by saying it returns categories, servers, tool counts, and the dedicated endpoint, and that it is free. It omits auth/rate-limit details, but those are less critical given the read-only 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 what the tool returns and is generally efficient. The parenthetical about tool-router and the endpoint URL add some density, but each part contributes usage or content context.

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 zero parameters, read-only annotations, and an output schema available, the description supplies enough context for correct invocation. It explains the catalogue contents and gives the category-specific endpoint alternative, leaving no critical gap for an agent.

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 parameter semantics are not a meaningful differentiator. The schema has no properties to explain, and the description does not need to document any inputs.

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 that this tool gives a catalogue overview: categories, servers per category, tool counts, and a dedicated endpoint. The resource is specific and recognizable, though sibling differentiation is only partial because it references 'tool-router' rather than the listed siblings like search/use.

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 alternative: use the category-specific endpoint if you only need one category, rather than going via search. It also notes the tool is free and AIsa-only, but it does not explicitly state when to call list_categories instead of search or use.

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 frames this as a benign read ('Fetch... return clean, structured page content'), yet the annotations declare readOnlyHint=false, destructiveHint=true and idempotentHint=false, and the description never reconciles that. An agent combining both sources cannot tell whether calling this mutates or destroys anything. Per the contradiction rule, this is scored 1 despite otherwise useful detail about the response envelope and billing.

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 and output are front-loaded in the first sentence, followed by required-argument and usage notes in efficient order. The generated pricing comment block and the double space before 'failed requests' add noise, but the prose itself wastes no sentences.

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-URL fetch with an output schema, the description covers the required argument, the response envelope, the billing implication of failures, and a companion tool — enough to invoke it correctly. The one real omission is that it does not address or explain the destructive/readOnly annotations, and it ignores competing scrape/extract siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is one parameter at 0% schema description coverage, so the description must carry the load, and it only repeats '`Url` is required' — the same information already in the schema property text. It does not clarify that Url is nested under the required `body` wrapper, nor give accepted URL forms, limits, or timeout/redirect behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Fetch a single URL') plus the concrete output ('title, body text, and publish time'), so an agent knows exactly what it produces. It names one sibling (post_byteplus_web_search) as a companion, but does not distinguish itself from the many other URL-content siblings (post_firecrawl_scrape, post_tavily_extract, post_exa_contents), leaving overlap unresolved.

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?

'Use it to extract full page content for URLs you already have, typically pairing it with post_byteplus_web_search results' gives a clear triggering condition and a workflow pairing. It provides no when-not guidance and never explains why an agent should pick this over the equivalent scrape/extract siblings, so the routing question is only half answered.

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 openWorldHint=true and destructiveHint=true, so the safety profile is partly covered; the description adds value annotations cannot express: per-request billing ($0.0048) and the fact that failed requests are not charged, plus upstream quirks (silently ignored TimeRange values, array input returning error 10400 in schema). It never addresses what the destructiveHint=true would mean for a search call, leaving a small ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then constraints, then response shape, then use cases and pairing — a sensible order with no filler. It is slightly heavy for a search tool (pricing block, a stray double space and lowercase sentence start before 'failed requests are not charged'), but every sentence carries 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?

An output schema exists, so return values need not be explained, yet the description still sketches ResponseMetadata.RequestId and a Result list. With one required nested body parameter and two nested Filter fields, the coverage is adequate; only error/failure behavior beyond billing and rate-limit expectations is left unstated.

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 reported as 0%, so the description has to carry meaning, and it does enumerate Query (required), Count (≤20), Filter with Sites/BlockHosts, Language, and TimeRange. However it only names them — the pipe-separated domain format, max-5 limit, and custom YYYY-MM-DD..YYYY-MM-DD range syntax live only in the schema, so the description adds little beyond the parameter names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Run a real-time web search') and names the output shape (ranked titled results with links and snippets), which is concrete and actionable. It clearly identifies the companion tool post_byteplus_fetch, but does not distinguish itself from the many other search siblings (post_exa_search, post_tavily_search, post_firecrawl_search), so an agent still needs external judgement to pick this 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?

Gives concrete use contexts (RAG augmentation, competitive/PR monitoring, fact-checking, content sourcing) and an explicit follow-up action ('pair each result URL with post_byteplus_fetch to pull full page content'). It stops short of any exclusion or 'use X instead when...' rule versus competing search providers, which is the only missing piece.

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 flag this as a destructive, non-idempotent, open-world write, so the description adds genuine extra context: owner scoping, admission-control behavior (disabling admission doesn't affect existing reads/cancellation), runtime availability and access-policy gating, and a cost estimate (~$0.10 default, not a fixed price). That is meaningful operational disclosure beyond structured fields, though it omits the read-only quote mode implied by the X-AISA-Cost-Mode parameter.

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?

It is short and contains no padding, but it front-loads the least useful sentence (abstract lifecycle/admission boilerplate) instead of the purpose. The pricing block is clearly delimited, and every sentence is terse, so structure is acceptable but misprioritized.

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?

An output schema exists, so return values need not be described. However, for a job-submission tool with a required Idempotency-Key and a quote-only cost mode, the description leaves out what the job actually does, how the quote mode interacts with submission, and how this differs from the sibling get/cancel endpoints.

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 75%, so the schema already documents query, effort, Idempotency-Key, and cost-mode parameters. The description adds nothing about any parameter, including the required Idempotency-Key or the quote mode; baseline 3 applies 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 'Owner-scoped local asynchronous job lifecycle', an abstract governance phrase rather than a verb+resource statement. It never says this tool submits/starts an Exa agent run for a query, and it does not distinguish itself from siblings like get_exa_agent_run, get_exa_apis_v1_exa_agent_runs, or post_exa_apis_v1_exa_agent_runs_jobid_cancel. Only the title ('submit') carries the actual purpose.

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?

There is no explicit when-to-use guidance. The sentence 'Disabling new admission does not disable existing job reads or cancellation' weakly implies this tool is the 'new admission' path and that reads/cancel live elsewhere, but it never names an alternative or states a condition for choosing this tool.

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?

It discloses return fields (requestId, answer, citations[], costDollars) and a latency figure, which the annotations do not cover. However, the annotations declare readOnlyHint=false and destructiveHint=true for what the description frames as a plain retrieval/answer operation, and the description never reconciles or even acknowledges that mutability/safety profile. The pricing sentence is hedged boilerplate ('not a fixed price'), so the added behavioral value is moderate.

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?

It is front-loaded well: purpose, key params, and return shape come first. But several sentences are promotional or boilerplate ('Measured at 2.1 seconds with 8 citations', 'Use current endpoint pricing and a fresh quote', 'compare current quotes when choosing a provider') and do not help an agent invoke the tool.

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?

An output schema exists, so the description is not obligated to enumerate return values, yet it still summarizes them concisely. The nested request body's enum and streaming options are the main uncovered area, and the mismatch between the destructive annotation and the read-style operation is left unaddressed.

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 reported at 0% for the top-level 'body' wrapper, so the description carries extra weight, and it does document query (required), text (includes source text) and outputSchema (shapes a structured reply). It says nothing about the important 'type' retrieval-mode enum (auto/fast/instant/deep-lite/deep/deep-reasoning) or the 'stream' flag, leaving the highest-variance parameter undocumented.

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: 'Ask a question and get a written answer with citations.' It also explicitly positions the tool against named siblings ('between a search and a research run'), so an agent can tell it apart from post_exa_search and post_exa_agent_runs without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear selection context with named alternatives: faster/cheaper than post_exa_agent_runs and more direct than reading post_exa_search results yourself. It also adds a domain cue ('when the retrieval needs to be semantic'). It stops short of explicit when-not conditions, and the closing 'compare current quotes' line is provider-shopping filler rather than 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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds some beyond-annotation context (owner scoping, admission-disable not affecting existing reads/cancellation, runtime/access-policy constraints), but it never explains what cancellation actually does or whether it is reversible, so the added value is thin and somewhat cryptic.

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 leads with a vague lifecycle statement rather than the cancel action, and it appends boilerplate pricing markup irrelevant to invoking the tool. Structure is not front-loaded and includes waste.

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?

An output schema and annotations exist, so return values and safety need not be restated, but for a destructive, non-idempotent cancel operation the description still omits what it destroys and any prerequisites beyond a vague access-policy note.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for the single jobId parameter, and the description says nothing about it (e.g., format, where the ID comes from). With low coverage the description is expected to compensate, and it does not.

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 never states that this tool cancels a job; it only says 'Owner-scoped local asynchronous job lifecycle,' which describes a domain, not an action. Only the tool name/title ('cancel') convey the verb+resource, so an agent must infer purpose from metadata rather than the description.

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?

There is no when-to-use guidance and no comparison to siblings like get_exa_agent_run or post_exa_agent_runs. The line about disabling new admission is a policy nuance, not a usage condition, so the agent gets no routing signal.

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?

Adds real context beyond the annotations: cache-hit vs. live-crawl fallback semantics, a measured latency figure, and the important failure-mode disclosure that unfetchable URLs surface in `statuses[]` instead of raising. It does not, however, reconcile the surprising destructiveHint=true / readOnlyHint=false annotations for what is nominally a fetch operation, which would have been valuable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the required parameter, then behavior, then the sibling alternative. The trailing pricing sentences ('Use current endpoint pricing and a fresh quote') and the injected pricing block are boilerplate that dilutes an otherwise tight description.

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 nested-schema fetch tool with an output schema, the description covers what matters: inputs, cache/livecrawl behavior, and the non-obvious `statuses[]` error channel. Return-field detail slightly duplicates the output schema, but the failure-mode explanation is genuinely additive.

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?

Reported schema coverage is 0% at the top level (the `body` wrapper is undescribed), so the description carries the burden and does it well: it names `ids` as required, explains its origin and format, and enumerates the `text`, `highlights`, `summary`, `subpages` and `livecrawl` toggles in prose.

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?

Opens with a precise verb+resource+scope: 'Fetch page text and metadata for URLs you already have.' It explicitly positions itself relative to post_exa_search (source of the `id` values) and post_firecrawl_crawl (whole-site alternative), so an agent can distinguish it from siblings without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

States the precondition ('URLs you already have', `ids` required) and clarifies that ids are plain URLs so any URL works. It also names the alternative and the condition that selects it: 'For a whole site rather than a URL list, 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 declare the safety/cost profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true), but the description adds genuinely useful context the annotations cannot convey: results carry no page text unless `contents` is passed, measured latency of ~1.4s, and per-request billing. It does not explain the unusual destructive/chargeable nature flagged by annotations, leaving a small gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads what the tool is, then constraints, then routing, with the pricing caveat fenced into a block. It is dense and mostly earns its space, though the return-field enumeration is partly redundant with the output schema and could be trimmed.

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 search endpoint with an output schema present, the description need not enumerate return fields, yet it does, and it covers the critical gotcha (no page text by default) plus cost and latency. Missing only a note on the remaining body options and why the endpoint is billed/destructive.

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?

With reported schema coverage at 0%, the description must carry parameter meaning, and it does name `query` as required plus the filter set (category, includeDomains, excludeDomains, date bounds, numResults) and the `contents` option. However `type`, `stream`, `outputSchema`, and `systemPrompt` go unexplained, so the coverage gap is only partially closed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search the web by meaning rather than by keyword') and immediately differentiates its retrieval mode from keyword search. It names the sibling tools it competes with (post_tavily_search, post_exa_answer) so an agent can place it in the toolset without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing guidance: 'Choose it over post_tavily_search when the query is a description rather than keywords; choose Tavily when you want the text in the same call, and post_exa_answer when you want a written answer rather than a list.' It also states when to pass `contents` versus following up with post_exa_contents.

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=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered structurally. The description's only real addition is implying the call is asynchronous and owner-scoped; it says nothing about what gets consumed, auth requirements, or the meaning of the required Idempotency-Key given idempotentHint=false.

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 text is short but dominated by a generic pricing boilerplate block that carries no tool-specific information. The one substantive sentence is front-loaded but vague, so brevity here reflects under-specification rather than conciseness.

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?

An output schema exists, so return values need not be explained. Everything else is missing: the tool's actual operation, how the submitted job is tracked, sibling routing, and any semantics for its four parameters in a nested body.

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 75%, below the 80% threshold, so the description needs to compensate and does not. None of urls, maxAge, minAge, timeout, includeTags/excludeTags, maxConcurrency or onlyMainContent is clarified beyond the schema, and the nested body structure is never mentioned.

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 never states that this tool submits a batch scrape job for a list of URLs; 'Owner-scoped local asynchronous job lifecycle' restates a category rather than a verb+resource. An agent must fall back to the tool name and title to infer the actual action.

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?

No when-to-use guidance and no routing to siblings. It never distinguishes this from post_firecrawl_scrape (single URL) or from get_firecrawl_batch_scrape_job, which is the tool an agent would need to poll after submitting. The admission-control sentence is unrelated to 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 destructiveHint=true, openWorldHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered elsewhere. The description adds only vague async-lifecycle and pricing boilerplate, and says nothing specific about job creation, polling via get_firecrawl_crawl_job, rate/limits, or the quote path even though a cost-mode parameter 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?

It is short, but the opening sentence is not front-loaded with the tool's purpose, and the aisa-pricing HTML comment block is filler that does not earn its place for an invocation decision. Structure prioritizes platform boilerplate over the crawl action.

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, nested-object crawl submission with a required Idempotency-Key and an output schema, the description omits purpose, usage, return-job semantics, and how to retrieve results. An agent has essentially nothing usable beyond the name and title.

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 75%, so the schema already documents most parameters (url, limits, path filters, scrapeOptions, Idempotency-Key, X-AISA-Cost-Mode). The description adds no parameter meaning whatsoever; the pricing note gestures at cost mode but with no actionable detail. Baseline 3 applies given the strong 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 never states that this tool submits a web crawl. 'Owner-scoped local asynchronous job lifecycle' is generic platform boilerplate that names no verb or resource tied to crawling, so an agent must fall back on the tool name/title to guess the purpose. It is at best vague and arguably misleading about what the tool actually computes.

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?

No when-to-use guidance is given, nor any routing to alternatives such as post_firecrawl_scrape, post_firecrawl_map, post_firecrawl_batch_scrape, or post_tavily_crawl. The admission-control sentence ('Disabling new admission does not disable existing job reads or cancellation') is a policy note, not a usage condition.

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=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, but the description discloses nothing about behavior, side effects, permissions, or rate limits. The only content is pricing boilerplate, which does not add any behavioral context 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 text is short, but every word is pricing boilerplate that does not help select or invoke the tool. Brevity here reflects absent content rather than efficient communication of the tool's 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 destructive, open-world POST tool with a nested object parameter and zero schema descriptions, the description supplies none of the required context. An output schema exists, so return values need not be explained, but purpose, usage, and parameter meaning are all 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 single nested body parameter (with url and limit) has 0% schema description coverage, so the description must compensate and does not. It gives no hint about what url or limit mean, valid ranges, or expected formats, leaving the parameter effectively undocumented everywhere.

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 never states what the tool does. It contains only billing metadata ('Usage-based billing; Default request estimate: $0.001071 USD'), which is a pricing note rather than a purpose statement. The agent must infer the function purely from the name 'post_firecrawl_map'.

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?

There is no when-to-use guidance, no mention of alternatives such as post_tavily_map, post_firecrawl_crawl, or post_firecrawl_scrape, and no preconditions. Nothing in the text helps an agent decide between this tool and its numerous 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?

The only behavioral content is a cost estimate ($0.001071 USD per firecrawl_credit), which is genuinely useful budget context not present in the annotations. However, it says nothing about what the operation actually does to the target URL, rate limits, or response behavior, and the provided annotations (destructiveHint=true, openWorldHint=true) receive no elaboration or corroboration.

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?

It is short, but every sentence is billing boilerplate wrapped in HTML comment markers rather than tool-relevant content. Nothing meaningful is front-loaded, so length efficiency buys nothing here.

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?

An output schema exists so return values need not be explained, but the remaining burden is entirely unmet: for a single-URL fetch tool sitting in a dense family of Firecrawl and other search/extract siblings, the agent gets no statement of purpose, scope, or selection criteria. This is inadequate for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the single 'body' parameter is a nested object with required 'url' and 'proxy' fields and constrained 'formats'/'onlyCleanContent' enums. The description supplies no parameter meaning at all — not even that a URL is required or that PDF targets are forbidden — so it fails to compensate for the zero coverage.

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 never states what the tool does — it contains only an auto-injected pricing/billing block. Nothing in the text indicates that this fetches and extracts content from a single URL, or distinguishes it from siblings like post_firecrawl_crawl, post_firecrawl_map, or post_firecrawl_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?

There is no usage guidance whatsoever: no when-to-use, no when-not-to-use, and no mention of the many sibling tools (crawl, map, batch_scrape, search) that an agent must choose between. The agent is left to infer everything from the tool name alone.

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 destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is externally supplied. The description adds only pricing-per-call context, which is useful operational context but does not explain what 'destructive' means for a search or describe authentication, rate limits, or result 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 text is short, but it is front-loaded with billing boilerplate rather than the tool's purpose. None of its sentences help an agent decide to select or correctly invoke this tool.

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 search tool with a nested request body, several sibling alternatives, and an output schema, the description omits purpose, usage, and parameter semantics entirely. It is not remotely complete enough to guide 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?

The schema has 0% description coverage and a nested body object, but the description provides no parameter meaning at all. Neither the required query field nor the limit, sources, or enterprise options are explained.

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 never states what the tool does. It contains only billing/pricing boilerplate, leaving the agent to infer 'search' from the name and title alone. Sibling tools include many competing search endpoints, so no differentiation is provided.

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?

There is no guidance on when to use this search tool versus alternatives such as post_exa_search, post_tavily_search, or post_perplexity_sonar. No prerequisites, query constraints, or exclusion conditions are mentioned.

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?

Adds valuable context beyond the annotations: ~3 second latency, that it is the cheapest/fastest of the four Perplexity endpoints, and the full response shape (choices[0].message.content, citations array, search_results fields, usage block). It does not discuss the odd destructiveHint=true annotation, auth needs, or rate limits, so it stops short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core capability and output form, then routing guidance, then cost. Dense but nearly every sentence is load-bearing; the response-field enumeration is slightly long given an output schema exists.

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-body parameter tool with an output schema, annotations, and sibling alternatives, the description covers purpose, output shape, latency, cost, and routing. Nothing an agent needs to choose or invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The top-level 'body' parameter has no schema description (coverage reported as 0%), and the description compensates by explaining the body is OpenAI chat-completions shaped with `model` (required, `sonar`) and `messages`. Nested properties are documented in the schema itself, so this is above baseline without being exhaustive.

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 and output form: 'Ask a question and get a written answer with web citations, rather than a list of links to read yourself.' That last clause sharply distinguishes it from link-returning siblings like post_tavily_search, and it names the resource family (Sonar/Perplexity) explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing guidance: 'use it for a single factual question,' step up to post_perplexity_sonar_pro for multi-part questions, 'post_perplexity_sonar_reasoning_pro' when steps are needed, and post_tavily_search when you need iterable results. This is a full when/when-not/alternative map.

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?

Adds behavior beyond the annotations: the operation takes long enough that 'many clients time out well before it answers', must not be looped, and carries usage-based billing with a concrete default estimate. It does not explain why the tool is flagged destructiveHint=true (a surprising trait for a research call) or address auth requirements, so it falls just short of full 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?

Front-loaded with the purpose, then scope limits, then alternatives — dense and largely waste-free. The sentence enumerating `choices[0].message.content`, `citations`, `search_results[]` and `usage` is partly redundant given an output schema exists, which costs a little tightness.

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 high-latency, high-cost, open-world POST with an output schema and rich annotations, the description covers purpose, inputs, outputs, latency, cost, and routing alternatives. Nothing an agent needs before deciding to call it 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?

With a single top-level `body` parameter and reported 0% schema coverage, the description compensates by naming the required inputs and pinning the model choice to `sonar-deep-research` — a constraint the schema's four-value enum does not enforce. It stays silent on the sampling, search-context, and domain-filter sub-parameters, which are the ones most likely to be mis-set.

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 gives a specific verb and artifact: 'Commission a report: this endpoint runs many searches and writes a long, cited document.' It also differentiates from siblings by contrasting with 'the other three Perplexity endpoints' that 'answer in seconds', so an agent can place it relative to post_perplexity_sonar, sonar_pro, and sonar_reasoning_pro without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use and when-not: 'call it only when a report is genuinely the deliverable, and never in a loop', with a named alternative class for lighter needs. Both the positive condition and the exclusion are stated, which is exactly what routing between four near-identical Sonar siblings requires.

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?

Adds real context beyond annotations: a per-request cost estimate, a latency comparison against the sibling, and the required model value. Annotations declare openWorldHint=true and destructiveHint=true, which the description never explains, so the odd safety profile is left unexplained — but the description does not claim the operation is read-only, so this is an omission rather than a contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose, then the request/response contract, then the selection criteria — three dense sentences with no filler. The pricing block is machine-generated boilerplate rather than authorial padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return fields need not be explained, yet the description still names choices[0].message.content, citations, search_results[] and usage, which helps the agent consume the result. Cost and routing are covered; streaming behavior and the missing param guidance are the residual gaps.

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 description usefully pins down `model` as required and `sonar-pro`, which the enum of four models in the schema does not. However with schema description coverage reported at 0% for the request, the remaining fields (search_context, return_citations, stream, filters) get no guidance from either source, so the description only partially compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Ask a question that needs more than one search pass and get a written answer with citations') and explicitly positions it against two named siblings, post_perplexity_sonar and post_perplexity_sonar_reasoning_pro. An agent can route without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use ('questions with several parts or follow-ups'), names the cheaper/faster alternative for single lookups ('sonar answers in a third of the time at the same price'), and names the alternative for reasoning-heavy work. Conditions for each branch are spelled out.

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 open-world, non-idempotent, destructive-cost profile, so the bar is lower; the description still adds the input contract (model must be `sonar-reasoning-pro`, messages in) and the output contract (`choices[0].message.content`, `citations`, `search_results[]`, `usage`). The embedded pricing note also flags usage-based billing. It stops short of auth, rate-limit, or streaming behavior details.

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, then I/O shape, then sibling routing — a front-loaded ordering with no throwaway sentences. The only non-authored text is the vendor pricing block, which is boilerplate the author cannot condense.

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, the description is not obligated to document returns, yet it does so briefly, and annotations carry the safety profile. For a nested 13-property body it names only the required pair, but combined with schema descriptions and the sibling routing it is sufficient to call 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?

Top-level schema coverage is reported at 0% (the `body` wrapper is undocumented), so the description must compensate, and it does by pinning the required enum value for `model` and describing the `messages` input shape. It adds no guidance on the optional tuning knobs (`search_context`, `top_k`, `return_citations`), which the nested schema does document.

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 names a specific verb and resource — ask a question that requires reasoning and receive a step-by-step, web-search-backed answer — rather than a generic 'query' framing. It explicitly distinguishes itself from two siblings by naming them (`post_perplexity_sonar` for lookups, `post_perplexity_sonar_deep_research` for long reports), so an agent can place it precisely in the family.

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 positive use cases (comparison, causation, analysis) and explicit exclusions with the routing alternative for each: simple factual questions go to `post_perplexity_sonar`, long multi-source reports go to `post_perplexity_sonar_deep_research`. A negation and its counterpart tool are both stated, leaving nothing to inference.

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

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

Without relying on annotations it discloses the return shape and size (~2 KB JSON vs ~177 KB for the SSE modes), explains that each streamed event repeats the whole answer so a tool call cannot consume it incrementally, and states the cost ($0.01). That is far more than the annotations provide. It does not, however, reconcile the declared destructiveHint=true / readOnlyHint=false for an operation the description frames as a pure explanation, so the mutation profile of this call is left unexplained.

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?

Key constraint is front-loaded, and the SSE-size comparison earns its length by justifying the response_mode recommendation. Some sentences restate schema content (the enum meanings of COMPLETE/INCREMENTAL/NON_STREAMING), and the pricing block plus emoji/bold add visual noise, but overall it is proportionate to the tool's complexity.

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 nested-body tool with streaming modes and a cost, the description covers purpose, inputs, response format, cost, and the hard limitation. An output schema exists, so it need not detail return values, and it briefly does anyway. The only uncovered area is the destructive/read-only behavior the annotations assert, which the description never addresses.

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?

Reported schema coverage is 0% (the top-level 'body' wrapper carries no description), so the description has to compensate, and it does: it enumerates search_id (with its origin), detail_level, language, and response_mode, and adds non-obvious meaning by prescribing NON_STREAMING and tieing search_id to a prior search call. The one gap is that, like the schema, it enumerates nothing about defaults for language/detail_level.

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 ('Explain a result set you already fetched') and immediately differentiates itself from the sibling search endpoints by noting they produce the search_id it consumes. An agent can tell what this does and how it differs from post_scholar_search_web/scholar/mixed 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 precondition explicitly ('a result set you already fetched'), names the three sibling tools that generate the required search_id, and states the exclusion 'it cannot run one.' It also gives concrete selection guidance for response_mode ('Use response_mode: NON_STREAMING'). This is explicit when/when-not/alternative coverage.

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?

Adds real operational context beyond the annotations: parameters belong in the query string, entry shape varies by source with authors/number_of_citations being optional, and latency is ~3 seconds. It does not, however, reconcile the surprising destructiveHint=true / readOnlyHint=false annotations with what is presented as a retrieval call, which is a genuine transparency gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and scoping in the first sentence, then return shape, latency, and routing. The parameter-location warning and the pricing boilerplate make it denser than ideal, but every sentence carries 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?

An output schema exists so return values need not be fully restated, yet the description usefully summarizes the variable result entry shape. With annotations and schema present, the only missing piece is any explanation of the destructive/non-read-only flags.

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 something the schema does not: that all four parameters are passed in the query string, with query required and as_ylo/as_yhi as bounds. It also flags that result fields authors and number_of_citations should be treated as optional.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and combined resource ('Search the web and academic sources together') plus the scenario it serves ('questions that straddle both'). It explicitly names the two siblings it is not, so an agent can differentiate it without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit positive condition ('when you do not know in advance which kind of source will answer') and the negative routing ('post_scholar_search_web or post_scholar_search_scholar is more predictable'), plus a follow-up rule to keep the id for post_scholar_search_explain. Nothing is left to inference.

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

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

Annotations declare readOnlyHint=false and destructiveHint=true, but the description presents a non-destructive search that returns an id and results and says nothing about destructive side effects. This directly contradicts the safety profile encoded in annotations, so the score is 1 and the contradiction flag is set.

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 definition is dense but front-loaded: purpose, parameter placement warning, return fields, timing, usage guidance, and sibling routing. The embedded pricing footnote is extraneous and adds length, but overall the structure is efficient and each main 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?

An output schema exists, so return-value details are not strictly required, though the description helpfully summarizes key fields. It covers alternatives, timing, and follow-up id handling, but it leaves a serious behavioral gap by omitting any mention of the destructive/non-readOnly annotation. For a tool whose annotations contradict its apparent search behavior, the description is not fully complete.

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 baseline is 3. The description adds a meaningful invocation detail absent from the schema: parameters go in the query string, not a body, and it groups the year-bound parameters as as_ylo/as_yhi. That extra transport guidance raises the score to 4.

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 ('Search academic literature') and distinguishes the tool from siblings by naming general web search and the mixed-mode alternative. An agent can tell this is the scholarly-article search tool 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?

It gives explicit when-to-use guidance ('peer-reviewed sources or when citation counts matter') and when-not guidance ('current events and product pages a general engine is better: post_tavily_search'). It also routes combined scholarly/web needs to post_scholar_search_mixed and follow-up explanation to post_scholar_search_explain.

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?

Discloses a non-obvious transport quirk (POST but parameters in the query string, JSON body rejected), the exact return shape (id plus results[] with title/link/snippet only), approximate latency and payload size, and the absence of page text. Annotations declare destructiveHint=true and readOnlyHint=false, and the description is consistent with a network-calling search rather than contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action and the transport warning, and the routing hint to post_tavily_search lands early. A few sentences are stylistic filler ("Its virtue is how little it returns") and the pricing comment block adds noise, so it is efficient but not waste-free.

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?

An output schema exists, yet the description still pins down the practical contract: transport method, required query, result fields, the returned id and its downstream use, cost, and expected latency. Nothing an agent needs in order to invoke and chain this call correctly is left implicit.

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 genuinely useful calling-convention detail: the parameters must go in the query string, a body is not accepted, and it restates the default (10) and ceiling (100) in prose. That is meaningfully beyond the schema's field-level 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?

States a specific verb and resource ("Search the open web and get back a lean result list") and characterizes the output shape, so the agent knows this is a lightweight web search rather than a content-fetching tool. It does not differentiate itself from the similarly-named siblings post_scholar_search_scholar and post_scholar_search_mixed, which an agent would otherwise confuse it with.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear selection rule: use this when you only need to know what exists, and use post_tavily_search when you need page content, plus a follow-up hook (keep the id for post_scholar_search_explain). It stops short of explicit when-not guidance against the other scholar search variants listed as 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 only declare the safety profile (readOnly=false, destructive=true, openWorld=true, idempotent=false). The description goes well beyond that: it discloses synchronous vs background execution, an observed latency (~4.5s at a 3-page limit), that cost and time scale with the bounds, and even billing rates. No contradiction with 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?

Front-loaded with purpose, then steering, then bounds, then alternatives — a good information hierarchy. It is dense with several parallel clauses and a boilerplate pricing block, but essentially every sentence carries routing or cost information an agent needs.

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 high-parameter, open-world, cost-incurring crawl tool this covers the decision-relevant surface: what it does, how to steer and bound it, how long it takes, what it costs, and which sibling to use instead. An output schema exists, so return values need not be re-explained, and the description still sketches them usefully.

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?

Reported schema coverage is 0% at the top level, so the description carries real burden and does so for the steering and bounding parameters: url, instructions, regex path/domain filters, max_depth, max_breadth and limit, with their roles explained. It does not touch format, timeout, extract_depth, chunks_per_source or the include_* toggles, so it does not fully compensate for the coverage 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?

States a specific verb and resource ('Walk a site from a root url and return the content of the pages it finds') and immediately distinguishes itself from siblings by naming post_firecrawl_crawl, post_tavily_extract and post_tavily_map with the conditions that select each. An agent can route correctly 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?

Explicit when-to-use ('broad coverage of one site — documentation, a catalogue, a competitor's blog') and explicit alternatives: extract for a handful of known pages, map to size a site first, firecrawl_crawl when the crawl is too large to wait on synchronously. When-not guidance is effectively present via the sibling comparisons.

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?

Goes well beyond annotations by disclosing that unfetchable pages land in failed_results[] rather than raising an error, that one page takes about 1 second, and the cost basis of the call. The verb 'Fetch' reads as read-only while annotations declare destructiveHint=true/readOnlyHint=false, but the description never asserts a safety profile, so this is a mismatch rather than a stated contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core verb and resource, then proceeds through input, output, tuning, latency, and alternatives in a logical order. Dense but nearly every sentence carries decision-relevant information; the appended pricing block is boilerplate that adds length.

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?

An output schema exists, so return-value explanation is optional, yet the description still surfaces the one operational hazard an agent must know: failures are reported in failed_results[] instead of surfacing as errors. With usage routing, latency, and billing all covered, nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is reported as 0% at the wrapping level, so the description must carry parameter meaning; it covers urls (required, multi-valued), format, and extract_depth. It says nothing about query, timeout, chunks_per_source, include_images, include_favicon, or include_usage, so it only partially compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — fetch clean, parsed content for URLs you already have — and immediately scopes the input source (a search result, sitemap, or user). It is clearly distinguishable from post_tavily_search and post_tavily_map, which are named as different operations.

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 when to use it ('whenever you can already name the pages'), why the alternative is worse ('searching for pages you can name costs more and may not return them'), and routes two other cases to named siblings: post_firecrawl_batch_scrape for long async lists and post_tavily_map for URL discovery.

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 real behavioral context beyond the annotations: no page content is fetched, ~1.5s latency, and a usage-based cost. However, it never reconciles the annotation profile (readOnlyHint=false, destructiveHint=true) — the text reads as a harmless listing while the annotations warn of a destructive, non-idempotent operation, and the agent gets no guidance on which to trust.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded: the core operation and its scope land in the first clause, then filters, return shape, cost/speed, and sibling routing. Dense but every sentence carries information; the only dead weight is the boilerplate pricing block.

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?

An output schema exists, yet the description helpfully pre-empts the biggest return-value pitfall ('a flat array of URL strings, not objects') and names the envelope fields. With that plus sibling routing and latency/cost disclosure, little is missing except guidance reconciling the destructive annotation.

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?

Reported top-level schema coverage is 0% (the `body` wrapper is undocumented), though the nested properties all carry descriptions. The description reinforces the interaction model for `instructions` and the regex filter families (`select_paths`/`exclude_paths`/`select_domains`) but is silent on the cost-controlling knobs (limit, max_depth, max_breadth, timeout, allow_external), which matter for a billed tool.

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?

Specific verb+resource ('List a site's URLs from a root url') with an explicit scope qualifier ('without fetching any page content'), and it names the sibling tools it is not (post_tavily_extract, post_tavily_crawl). An agent can distinguish it from the other ~30 tools without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit workflow condition: 'Use it to size a site before committing to a crawl, then fetch only the parts that matter with post_tavily_extract', plus the contrasting case 'When you want the content rather than the shape, post_tavily_crawl does both in one call.' When-to-use and alternatives are both stated outright.

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?

Adds meaningful behavioral context beyond the structured fields: ~6 second latency at 2 results, the cost-vs-depth tradeoff exposed by search_depth, and the usage-based billing note. It also pre-empts a common follow-up by stating page text is already extracted. One gap: it never reconciles the destructiveHint=true/readOnlyHint=false annotations with what is plainly a read-only retrieval, so an agent reading the annotations alone would be misled; the description does not correct that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded correctly: capability and return shape first, then filtering/depth knobs, then latency, then sibling routing. Every sentence carries information. It is, however, a dense single block packing five distinct concerns (returns, params, latency, routing, billing) without visual separation, which slightly raises scan cost for an agent.

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?

An output schema exists, so return values need not be explained, yet the description names the key response fields (results[], query, images, response_time, request_id) for extra safety. Combined with filtering knobs, latency, cost, and explicit sibling routing, an agent has everything needed to choose 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?

The top-level schema exposes only the wrapper `body` object (coverage metric 0% at that level), yet the nested properties are individually documented. The description still adds selection guidance beyond the raw field docs: `query` is required, `topic`/`time_range`/`start_date`/`end_date` for filtering, `search_depth` framed as a cost-vs-depth dial, and `include_answer` framed as the way to get a one-paragraph answer. That is useful decision-level semantics rather than restated field text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (search the web) and immediately scopes it: ranked results with page text already extracted so no second fetch call is needed. It explicitly differentiates from siblings, claiming it is 'the only search here that returns ranked results and page text in one call,' which lets an agent separate it from post_exa_search, post_tavily_extract and post_firecrawl_search without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names itself as the 'default choice for open-web research' and then gives an explicit routing table: known URLs -> post_tavily_extract, descriptive/semantic query -> post_exa_search, want a written answer -> post_perplexity_sonar, peer-reviewed papers -> post_scholar_search_scholar. When-to-use and when-to-reach-past are both stated with the selecting condition for each 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, so the safety profile is covered. The description adds workflow behavior the annotations cannot: the has_full_schema flag gates a required batch_get_schema call, and the next step after search is batch_quote, not batch_use. It stops short of disclosing retrieval limits or catalog breadth that would push it to a 5.

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?

It is a dense run of imperatives rather than flowing prose, but each sentence carries a distinct rule (scope, language, workflow branch, negative cases, result interpretation) and the most important scoping guidance is front-loaded. Slightly more compression would help.

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, the description need not explain return values, and it correctly avoids doing so while still referencing the output fields that drive the workflow (has_full_schema, next_steps_guidance). A mutation-free, well-annotated search tool is adequately covered, though catalog scope ('AIsa-only', no external providers) could be stated more explicitly.

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 structured baseline is 3. The description adds genuine meaning beyond the schema by telling the agent to write the query in English and to place tickers, URLs, providers, or identifiers in known_fields, which is non-obvious routing guidance for a nested free-form object.

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: 'Discover AIsa tools and Plans for external data or actions.' It also separates this discovery step from the sibling execution tools by naming batch_get_schema, batch_quote, and batch_use and stating when each follows, so an agent can place it in the workflow 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?

It gives explicit when-to-use ('tasks needing external data or actions'), when-not ('tasks that only need supplied content or general knowledge'; no standalone rewriting, translation, summarization, formatting, or calculations), and named alternatives (batch_get_schema when has_full_schema=false, batch_quote rather than batch_use). It also specifies query language and atomic-query style, leaving little to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the agent knows this is a state-changing, open-world operation. The description adds only the deprecation status and says nothing about what gets mutated, spend behavior (despite a max_price_usd param), or authorization needs.

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?

A single clause with zero waste; the deprecation notice and the replacement are front-loaded. It is terse by design for a deprecated endpoint, though it is under-specified rather than optimally efficient.

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?

Has an output schema and annotations, which reduces the burden, but a 4-parameter operation tool with a deprecation notice gives no information about what it executes or whether it remains functional. For an agent deciding between this and batch_use, the description is thin.

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 four parameters (operation_id, arguments, search_id, max_price_usd) are already documented in the schema. The description adds no parameter meaning on top, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description never states what the tool does — no verb or resource. It only labels the tool as deprecated and points to a replacement, leaving the actual capability ('Run an AIsa operation' from the title) unexplained. An agent must infer the purpose from the title and schema alone.

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 routes the agent to the alternative ('use batch_use instead'), which is exactly the guidance needed for a deprecated tool. It doesn't explain when, if ever, this tool should still be called (e.g., during a migration window), so it stops short of a 5.

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