search-rotation

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

Annotations cover the safety profile (readOnly, idempotent, openWorld), and the description adds substantial behavior beyond them: provider rotation with failover across five named providers, a 50,000-character truncation with marker, the result naming the successful provider and listing failed attempts, and an all-providers-fail error enumerating each reason. That is exactly the extra context a caller 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?

Three tightly packed sentences, front-loaded with the core action and followed by usage routing and return/error behavior. No filler; every clause conveys operational 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?

With no output schema and a trivial input schema, the description carries the burden and does so: it explains return shape (Markdown content, provider name, failed attempts, truncation marker) and error semantics. Nothing an agent needs to invoke or interpret the call 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?

Only one parameter at 100% schema coverage, so the schema already documents it fully. The description still adds the accepted-scheme constraint (only http and https), which goes slightly beyond the schema, though URL formatting details remain with 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+resource (fetch one web page, return main content as Markdown) and explicitly contrasts itself with search_web by declaring it does not discover links or crawl a site. An agent can distinguish it from siblings immediately.

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

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

Gives the selection condition explicitly: use it to read a URL the user or a previous search_web result already names, with an explicit exclusion (does not discover links or crawl a site). The http/https-only constraint further bounds usage.

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 read-only/idempotent, but the description adds substantial non-obvious behavior: it is not a live health check, stored errors are historical, a disabled engine is not proof of a missing key, provider balances may come from a cached lookup, and unknown limits are reported as null rather than zero or unlimited. These caveats directly prevent misreading the output.

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 purpose is front-loaded in the first clause, followed by usage and then caveats, so the ordering is sound. The middle sentence is dense and long, and the description runs as a single paragraph, but nearly every clause carries 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?

With no output schema and no parameters, the description must convey what comes back, and it does: engine state, rotation order, per-capability credential requirements, counters, and quota source, plus the interpretation caveats. Nothing essential to calling or reading this tool is missing.

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

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

The tool takes zero parameters, so the baseline is 4; the input schema is empty and there is nothing for the description to clarify. No credit above baseline is warranted, but there is no gap either.

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

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

States a specific verb+resource ('Read this server's local engine configuration') and immediately enumerates what is returned: enabled state, rotation order, per-capability access, usage counters, quota source. This cleanly distinguishes it from search_web, fetch_url, and open_dashboard.

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: 'before update_engine_config for valid engine ids' and 'when you need to know which providers are active, how much quota is left or why a provider is skipped'. It also routes the agent between alternatives, noting the dashboard is the human-facing view of the same data. 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 mark it non-read-only, non-destructive, non-idempotent, but the description adds the traits that actually matter: the browser launches on the server host rather than the caller's machine, this is the only path for entering API keys/provider credentials and strict-free mode, and it errors under --no-dashboard. That is substantive disclosure beyond the structured hints.

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?

Dense and front-loaded — the purpose and the 'for a human' qualifier come first, alternatives second, caveats last. It is a single long run-on sentence with some redundancy, but nearly every clause carries a distinct constraint.

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

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

With no parameters and no output schema, the description carries the full burden and does so: it covers what happens on invocation, where the browser opens, the error case, and when to prefer sibling tools.

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 baseline is 4. The description adds meaning by explaining what the dashboard UI is for (credentials, port, access token, usage/quota/history views), which is more than an empty schema conveys.

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 ('Open') and resource ('the local dashboard of this server') plus the crucial scope nuance that the browser opens on the server host, not the client. An agent can distinguish it from get_engine_status and update_engine_config without reading 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?

Explicitly routes: use this for credential/network settings and when a human should view the data, and use get_engine_status or update_engine_config instead for machine-readable reads/writes. It also names the failure condition (server started with --no-dashboard returns an error).

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 read-only, open-world, idempotent, non-destructive; the description adds substantial behavior beyond that: automatic failover on error, rate limit or exhausted quota, visibility of every failed attempt and the answering provider, and how time filters constrain rotation. It also documents the failure mode when all eligible providers fail, which is exactly the operational context an agent needs for retry decisions.

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

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

The important routing information is front-loaded in the first two sentences, and each subsequent sentence adds a distinct behavioral fact rather than restating the schema. It is dense and slightly long — the provider roster reads as a list dump — but nothing is genuinely wasted.

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

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

For a six-parameter tool with no output schema, the description covers what is returned (numbered results with title, URL, snippet, publication date, plus the answering provider and failed attempts) and the error contract. Combined with the fully documented input schema and read-only annotations, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning the schema does not: the engine parameter only reorders preference while failover stays active, and time filters deliberately fail rather than silently searching unfiltered. The remaining parameters (startDate, endDate, timeRange mutual exclusivity) are already fully documented in the schema, so no further credit is warranted.

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

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

The description opens with a specific verb and resource ("Search the web") and immediately narrows scope: it searches via a rotating pool of named providers with failover. It explicitly contrasts itself with the sibling fetch_url, so an agent can distinguish retrieval-by-query from retrieval-by-URL 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 states the selecting condition plainly: use this when the answer depends on current web pages and no URL is known yet, and use fetch_url when the URL is already known. It also names get_engine_status implicitly via the engine parameter, giving the agent a prerequisite step for preferring a provider.

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

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

Beyond the annotations, it discloses that the write targets the shared configuration file of the installation, applies to later searches of every client without a restart, rejects API keys, and that on error nothing is written. The atomicity guarantee is genuinely useful context for a mutation 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?

Three front-loaded sentences, the primary action first, followed by prerequisites and failure behavior; nearly every clause earns its place, though the credential paragraph is somewhat dense.

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

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

With no output schema, the description still explains the return value (effective per-engine configuration or an error naming offending ids) and the no-write-on-error behavior, covering what an agent needs for a 5-parameter nested-object mutation.

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

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

Schema description coverage is 100% and the schema itself richly documents each of the five parameters (rotation semantics, null-to-remove, access-mode failures). The description reinforces but does not meaningfully extend these meanings, so the baseline of 3 applies.

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

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

States a specific verb (Change) and resource (local engine configuration), then enumerates the three capabilities: enable/disable, rotation order, and call limits. An agent can distinguish it from search_web, fetch_url, get_engine_status, and open_dashboard 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?

Explicitly says when to use it (user wants a provider switched on/off, reordered or capped) and gives a prerequisite: call get_engine_status first for valid ids, current order and access modes. It also states when it will not work (engines needing keys must be set via open_dashboard).

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