Get port-out PIN status

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

Annotations indicate idempotent, read-only, and non-destructive behavior. The description adds value by stating the PIN is never returned and mentioning the specific error TN_NOT_OWNED, which helps agents handle failures. This goes beyond what annotations alone provide.

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?

Extremely concise: two sentences for the core description plus one for errors. Every sentence provides essential information without redundancy. The purpose is stated immediately, and additional context is efficiently given.

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 simple read-only check tool with one parameter and no output schema, the description is complete. It explains what is checked (PIN set, lock status, lock expiration) and what is not returned (PIN). No output schema is needed given the simplicity.

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 'tn' has 100% schema coverage, including format examples. The description does not add additional semantics beyond the schema, so it receives the baseline score of 3 for well-documented parameters.

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 it checks whether a port-out PIN is set and if locked out, with the locked_until timestamp. It specifically notes the PIN itself is never returned, distinguishing it from get-like tools that might return secrets. References to sibling tools num_set_port_out_pin and num_remove_port_out_pin clarify the broader context.

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 tells when to use this tool (to check PIN status or lockout). Provides clear alternatives for setting and removing the PIN. Does not explicitly state when not to use, but the context is clear considering sibling tools.

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