List my proxies and static IPs

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so "Read-only" is redundant, but the description adds a genuinely non-obvious behavior: passwords are masked unless include_credentials=true. That is a security-relevant disclosure an agent could not derive from the schema, which carries a bare boolean with no description. It stops short of covering pagination or what an empty result means.

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 clauses, each carrying distinct information, with the resource and scope front-loaded and the credential caveat immediately after. Nothing is wasted or repeated.

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 six optional params, zero schema descriptions, and no output schema, the description covers the interesting filters but leaves pagination and the active_only default unexplained. An agent could call it correctly for the happy path but would not know that inactive proxies are excluded by default or how to page through large accounts.

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% across six parameters, so the description must compensate and it only partially does: it explains include_credentials' effect and maps to the kind and billing enums. page, page_size, and especially active_only (which defaults to true and silently hides inactive proxies) get no explanation 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?

States a specific verb and resource ("List proxies on the account") and enumerates the two axes it can be sliced by (dynamic/static, billed by traffic/IP). It is clear what the tool returns, but it never distinguishes itself from the sibling get_dynamic_proxy, which an agent could plausibly confuse it with for a single-proxy lookup.

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

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

Usage is only implied: the description says what can be listed but never says when to reach for this versus get_dynamic_proxy or get_account_usage. The one guidance-like statement is the include_credentials condition, which is really a behavior note rather than a when-to-use rule.

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