get_proxy_replacements

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

With no annotations provided, the description fully covers behavioral aspects: it states the tool is read-only, describes the data returned (allowance, used amount, history), and clarifies that requesting a replacement is a write operation not available as an MCP tool. This is comprehensive for a simple read tool, though it could mention any limits on the history length or pagination.

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 consists of four focused sentences, each adding specific information: purpose, use case, read-only nature, and parameter source. It is front-loaded with the core function, and every sentence contributes meaningfully without repetition.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is complete. It explains what data is returned, how to use it (checking replacement availability), and the prerequisite for the id. It also addresses the relationship with the write counterpart, ensuring the agent understands the tool's role in the broader context.

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 only parameter, 'id', has a schema description of 'Proxy service id from list_proxies', and the description adds 'The id comes from list_proxies.' Since schema coverage is 100%, the baseline is 3. The added value is minimal, as the schema already explains the parameter adequately.

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

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

The description clearly states the tool retrieves 'IP-replacement allowance and history for a proxy service', specifying the data fields (monthly allowance, usage, past requests). It distinguishes from the sibling 'request_proxy_replacement' by noting that this tool is read-only and that the write operation is not yet exposed. The verb 'get' and the specific resource make the purpose unambiguous.

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

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

The description explicitly says 'Use to check whether a free IP replacement is available before requesting one', providing a clear use case. It also notes that the id comes from 'list_proxies', indicating a prerequisite. While it doesn't list cases when not to use, the context is sufficient to guide appropriate invocation, especially with the sibling differentiation.

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