nex_proxy_detect

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

With no annotations, the description carries the full burden. It discloses that credentials are never returned and implies a non-destructive 'probe' operation, but 'credentials are never returned' is already in the schema for username/password, so it adds limited new behavioral depth. It does not explicitly state read-only or confirm no modification, though 'probe' suggests it.

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 concise sentences front-load the action and resource, then add the credential safety note. Every word contributes, with no fluff or repetition of obvious schema details.

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?

The description covers the two input modes, key output fields (exit IP, location, timezone), and a security behavior. It lacks explicit mention of error/connectivity behavior and does not state read-only, but for a simple probe tool with 0 required parameters and no output schema, it is largely complete. Schema fills in protocol details.

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 high (86%), so the baseline is 3. The description compensates for the only undocumented parameter ('host') by framing it as part of an 'unsaved host:port', and it reinforces the proxyId vs host/port duality. This adds meaningful semantic context beyond 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 clear verb ('Probe') with a specific resource ('a proxy resource or an unsaved host:port') and the expected result ('exit IP, location, and timezone'). This immediately distinguishes it from sibling proxy tools like create/modify/delete/list, and the 'detect' suffix reinforces a diagnostic read operation.

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?

Provides clear context on two usage modes: probing a saved proxy resource (via proxyId) or an unsaved host:port. The phrase 'unsaved host:port' explicitly signals a non-saved input scenario, but it does not explicitly compare against alternatives or state exclusions, so it falls just 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.