create_certificate

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

Annotations provide destructiveHint=true, and the description adds context (automatic vs manual triggering) without contradicting it. However, the description doesn't explicitly disclose that renewing replaces/destroys the existing certificate, though the verb 'renew' implies it. With the annotation covering destruction, the marginal disclosure is adequate but not rich.

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 sentences with zero waste. The primary action is front-loaded, and the usage note earns its place by clarifying the manual-renewal case. Nothing extraneous.

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?

Complete for a single-parameter action tool. The description covers what it does and when to use it, annotations cover the destructive safety profile, and the schema fully documents the one required parameter. The only minor absence is expected return/response behavior, but with no output schema defined this is an acceptable gap.

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 coverage is 100% — templateId is already documented as 'Template id.' The description reinforces the parameter's role ('for a template') but adds no syntax or semantics beyond the schema. Baseline of 3 is correct when the schema carries the load.

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+resource ('Create or renew the Apple Wallet certificate') and the target ('for a template'). Unambiguous even against 25 siblings — it is the only certificate-related action, and the description further separates it from the automatic template-creation flow.

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 the agent this is 'for manual renewals' and that creation is 'usually triggered automatically on template create'. This is clear when-to-use context with no named sibling alternative (the alternative is automation, not another tool). Slight deduction because it doesn't spell out when not to call it.

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