isw_get_pin

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

No annotations are provided, so the description must fully disclose behavioral traits. It mentions 'sensitive operation' and 'redacts sensitive fields', but does not explain what 'redacts' means (e.g., whether the PIN is masked in the response), nor does it describe authentication needs, rate limits, or failure behavior.

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 is extremely concise with two sentences, no fluff, and front-loaded with the core purpose. Every sentence serves a purpose.

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?

No output schema exists, so the description should explain return values or error conditions. It does not specify what the tool returns (e.g., the PIN, a masked value, or a success indicator). It also lacks information on prerequisites or error handling, making it incomplete for an agent.

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 only 33% (only 'confirm' has a description). The description adds that 'confirm' is required as true, but does not provide any guidance for the other parameters ('cardPan' format or 'extra' usage). It adds minimal value 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?

Description says 'Get a card PIN', which clearly identifies the tool's purpose of retrieving a PIN. The verb 'Get' and resource 'card PIN' are specific, and it distinguishes from sibling tools like isw_reissue_card_pin or isw_change_card_pin by being a retrieval operation. However, it does not clarify whether the actual PIN value is returned or redacted.

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 states it is a sensitive operation requiring 'confirm: true', which is a usage requirement. However, it provides no guidance on when to use this tool versus alternatives like reissue or change PIN. It does not mention any prerequisites or context where this tool is appropriate.

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