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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the bar is lower. The description adds real value beyond that: auth requirement, the tickets:read scope, owner-private visibility that never spans accounts, and the fields each snapshot carries. It does not discuss pagination limits or failure modes.

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 action and scope options, then the payload contents, then auth. Every sentence carries information, though the payload-field enumeration is dense; it stays within reasonable length.

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?

No output schema exists, so describing the returned fields ('label, schema version, stored payload, content hash, recording actor, creation time') and ordering is essential and present. Combined with auth scope, privacy constraints, and scope/project_id requirements, an agent has everything needed to call it 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?

Schema coverage is only 33% (scope enum and project_id lack descriptions), so the description must compensate. It explains the three scope values and the project_id prerequisite, but says nothing about limit beyond what the schema already documents. It fills most of the coverage gap.

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 ('List ... snapshots'), names the three scope modes, and specifies ordering ('newest first') and what a snapshot is ('immutable rollups of how your ticket portfolio stood'). It does not explicitly differentiate itself from nearby siblings like get_portfolio_snapshot or diff_portfolio_snapshots, so it stops short of 5.

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?

Gives clear selection context: default is own portfolio, 'project' scope requires project_id, and 'all' is available. It does not name alternative tools or state when a different sibling (e.g. get_portfolio_snapshot for a single snapshot) should be used instead, so no explicit exclusions.

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