TracePass passports

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

Beyond annotations (only idempotentHint=false), the description discloses billing for create, irreversibility of archive, reversibility of suspend, and overage handling. No contradiction with annotations.

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 well-organized with sections and bullet points, but slightly verbose. However, the complexity warrants the length; no extraneous sentences.

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?

Covers all critical aspects: actions, billing, reversibility, overage, and read-only hints. Even without an output schema, the description provides sufficient context for an AI agent to select and invoke the tool correctly.

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?

Although the input schema has generic args object, the description details each action's required args (e.g., id, format, confirmOverage) and allowed values (e.g., status enum). This adds significant meaning 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?

The description clearly states 'Manage Digital Product Passports — create, read, and run lifecycle actions' and enumerates specific actions. It distinguishes itself from sibling tools like tracepass_epcis or tracepass_products by focusing on passport management.

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?

Provides explicit guidance: when to use confirmOverage, when to prefer suspend over archive (irreversible), and notes that list/get/get_by_serial/get_qr are read-only. Also warns about billing for create.

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