hsm_get_apc_mapping

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

No annotations are provided, so the description carries the behavioral disclosure burden. It clearly conveys that this is a lightweight read-only lookup, states exactly what it returns, and notes that no AWS credentials are required. It does not describe behavior for unknown command codes, keeping it from a perfect score.

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 compact and front-loads the most important routing information before the return behavior and parameter documentation. Every sentence earns its place, and the sibling comparison is concise rather than redundant.

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 one-parameter lookup tool, the description is complete: it explains when to use it, what it returns, and the credential requirement. There is no output schema, but the description names the returned fields clearly enough for an agent to understand the result.

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%, but the description compensates by explaining command_code as 'The HSM command code' and giving concrete examples ('TPIN', 'CA', '31'). It does not specify exact format or validation rules, but with a single required parameter, the provided semantics are sufficient for effective use.

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 opens with a specific verb and object ('command-code → APC operation lookup') and narrows the tool's output to 'the APC operation and key type.' It explicitly contrasts with hsm_lookup_command, so an agent can disambiguate the tool immediately.

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 gives explicit when-to-use guidance: use this when you already know the command and only need the migration target, and prefer hsm_lookup_command when you need the full description and notes. It also notes the tool works without AWS credentials, which is a clear contextual signal.

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