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

Goes well beyond the annotations (destructiveHint, idempotentHint), disclosing that each supplied parameter overwrites the stored value wholesale, that lists must be resent in full, that "" and [] clear values, that omitted parameters are preserved, that voided=True kills the pass on every device, that the push refresh is near-immediate, that changeMessage surfaces on the lock screen, and that the operation expires at updatable_until. This is exactly the mutation-side-effect detail an agent needs.

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?

Front-loaded with the core identity and precondition, then layered update semantics, then propagation behavior, then return contract. Every sentence resolves a real ambiguity (list replacement, no-op on omission, notified_devices counting sends not refreshes). No filler.

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 41-parameter mutation with no output schema, this covers returns, mutation semantics, expiry, and propagation, which is most of what an agent needs. The remaining gap is that individual parameter meanings are inherited by reference to the sibling tool rather than restated here.

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% across 41 parameters, so the description must carry the load. It does explain the replace-not-merge semantics, the clear-value syntax, voided, and where serial_number/edit_token come from, which is high-value, but it explicitly defers individual parameter meanings to create_wallet_pass rather than documenting them, leaving the per-field semantics external.

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 and resource ('Change a pass made with create_wallet_pass(updatable=True)') and immediately distinguishes itself from the create sibling by naming the upstream tool and the precondition for using this one. An agent can tell the two apart without opening either schema.

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?

Names the sibling tool and the condition that produces the pass being edited (updatable=True), and gives an explicit when-not boundary ('Only works until the pass's updatable_until time'). It stops short of an explicit routing sentence like 'to create a pass, use create_wallet_pass', so it is clear context rather than a full when/when-not/alternatives map.

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