ipvolt Proxy Toolkit

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 bar is lower. The description still adds real value by disclosing the output character ('returns uncertainty and retry boundaries') and an input-hygiene constraint that annotations cannot express.

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

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

Three short sentences, each earning its place: what to supply, what comes back, and what not to supply. Front-loaded with the actionable instruction and free of 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 values need not be enumerated, and the description still signals the uncertainty/retry-boundary framing. Combined with annotation coverage and reasonably documented enum fields, an agent has enough to invoke it correctly, though the exclusion from sibling tools remains 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 coverage is 56%, and the description names only four of nine inputs (client, version, phase, status/exception) without adding format or interpretation detail. The schema's own field descriptions (normalized exception category, response provenance, bounded Retry-After) do the heavy lifting, so this is adequate but not compensatory.

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 (identify possible causes and the next check) on a specific resource (proxy errors) using named inputs. It is clearly distinguishable from doc-search and config-generation siblings, though it never names them 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?

Gives strong input guidance ('use structured client/version, phase, status or exception observations') and a negative constraint ('do not send raw logs, URLs or credentials'), which effectively tells the agent when this tool is inappropriate. However, it never contrasts with search_proxy_docs, get_proxy_doc, or generate_proxy_config, so the routing decision is left implicit.

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, closed-world behavior, and the description is consistent with them. It adds genuinely useful context beyond the annotations: the output is a non-executed example, credentials/target are local placeholders, and no other agent tooling is touched. It does not mention what the generated snippet looks like structurally, but with a rich output schema that is 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?

Three short sentences, front-loaded with the core action, followed by the placeholder caveat and the non-execution boundary. No filler or repetition of the tool name or title.

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. The description covers the generation-only nature, the exact-version constraint, and placeholder semantics. It leaves unstated what the snippet actually contains (headers, env var wiring), but that is a minor gap for a simple generation tool.

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

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

Schema coverage is 75%, so the schema already documents client, version, and protocol. The description reinforces the key constraint that version must match the client and only exact tested versions work, but it adds no detail on protocol or timeoutSeconds beyond what the schema states. Baseline 3 fits.

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 (Generate) and resource (HTTPS GET example / proxy configuration) and names the exact client families covered. It implicitly separates itself from siblings like search_proxy_docs and diagnose_proxy_error because generation is a distinct action, but it never names an alternative 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?

The description implies usage context through 'exact tested ... version' and adds scope exclusions ('does not execute the example or configure other agent tools'). It stops short of saying when to pick this over search_proxy_docs or get_proxy_doc, so guidance remains inferred rather than stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description adds genuinely useful behavior: reads are bounded, and cursors are bound to the content revision (so a revision change invalidates them). It stops short of describing chunk size limits or what happens with an invalid/expired cursor.

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?

Two sentences, both load-bearing: the first states what is read and where the ID comes from, the second covers pagination and cursor invalidation. Front-loaded and 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?

With an output schema present, return values need no explanation, and the description adequately covers the fetch-then-continue workflow plus cursor lifecycle. The remaining gap is the section-vs-cursor relationship and cursor expiry behavior for a 3-parameter tool.

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

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

Schema description coverage is 0%, so the description must carry the load. It explains that documentId comes from search results and that cursor is a continuation token, which is meaningful, but the 'section' parameter is only named—no naming convention, case sensitivity, or interaction with cursor is given, even though the schema constrains its length to 160 chars.

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 precise verb+resource ('Read a bounded chunk or named section') and identifies the document ID source, which cleanly separates it from search_proxy_docs. An agent can tell immediately this is the follow-up fetch step rather than a search or config tool.

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 ties usage to a prior search_proxy_docs call that produced the document ID, and gives the continuation rule ('Follow nextCursor to continue'). It does not state when to prefer a section read over a cursor read, so it falls short of full when/when-not guidance.

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

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

Annotations already establish the read-only, idempotent, non-destructive, closed-world profile, so the bar is lower. The description still adds value the annotations do not: it names what comes back (canonical document IDs, excerpts, content revision) and imposes a security constraint against submitting credentials or logs.

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?

Two tightly packed sentences with the core action front-loaded and no filler. The return-value sentence is mildly redundant given an output schema exists, keeping it just below a 5.

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?

Annotations cover safety and an output schema covers return shape, so the remaining burden is small. Still, an agent gets no routing rule against get_proxy_doc and no guidance on the topic enum or result-limit behavior, which are the practical decisions when calling a search tool.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it only partially does. The query parameter's intent is hinted at ('short topic query'), but 'limit' and the five-value 'topic' enum are never mentioned, leaving two of three parameters undocumented anywhere.

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 ('Find reviewed ipvolt public guides and articles'), which is clearly distinguishable from the config-generation and error-diagnosis siblings. It stops short of naming get_proxy_doc as the tool for retrieving a full document by ID, so sibling differentiation against the closest alternative is only implicit.

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 only usage direction is input hygiene ('Submit a short topic query, never credentials or logs'), which constrains what to type rather than when to choose this tool over get_proxy_doc. There is no stated condition, prerequisite, or alternative for a multi-result search versus a single-document lookup.

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