create_pass

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

The annotations include destructiveHint: true, which already signals side effects. The description adds valuable behavior beyond that: it can optionally send pass links via email or SMS. This extra disclosure aligns with the annotation and provides useful context, though it does not cover other potential side effects like rate limits or reversibility, which are not required given the annotation coverage.

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 two sentences, front-loading the core function and then adding usage context and optional delivery methods. Every sentence serves a purpose, with no redundant text. It is concise and well-structured, making it easy for an agent to parse quickly.

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?

While the schema thoroughly documents parameters, the description lacks a mention of the return value (e.g., created pass objects or confirmation) and does not summarize the batch limit (1-10 per call) which is only in the schema. Given the tool's complexity and absence of an output schema, the description could provide more high-level context about expected outcomes or error handling to be fully complete.

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 100% and the schema provides detailed descriptions for all parameters, including nested fields like collectedStamps and templateFields. The description adds no additional parameter meaning beyond a high-level summary of the tool's purpose. Since the schema fully covers parameter semantics, a baseline score of 3 is appropriate.

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 states a specific action (create wallet passes) on a clear resource (templates/passes) and lists concrete use cases (loyalty cards, event tickets, coupons, membership passes). This clearly differentiates it from sibling tools like update_pass and list_passes, which operate on existing passes.

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 explains when to use the tool ('issue new... passes') which implies it is for creation, but it does not explicitly contrast with alternatives like update_pass for modifications or notify_pass for notifications. While the context is clear, it would benefit from naming the specific sibling tools it complements or replaces.

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