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

Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds substantial unannotated context: owner-private data, inclusion of deleted-ticket history, pagination via next_before_id while has_more, limit range, required scopes, no provider request or credential decryption, and a caveat about historical vs. current state.

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 dense and front-loaded, with the core read action stated first, followed by scope, pagination, permissions, and caveats. Every sentence carries useful information, though the phrasing is slightly compressed and could be marginally clearer.

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 read-only listing tool with no output schema and full annotation coverage, the description supplies the remaining necessary context: authentication requirements, no provider-side access, historical scope, pagination behavior, and the caveat that observations are not live state. Nothing critical for correct invocation appears missing.

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%, so the description must carry meaning. It compensates well by mentioning the limit range (1–100), provider scoping (Jira/Linear), ticket scoping, and pagination via next_before_id/has_more. It does not explicitly explain before_id's UUID format or directly map every parameter name, keeping it from a 5.

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 (List/Read) and resource (owner-private retained Jira/Linear status observations and effect evidence), with optional scoping. It does not explicitly distinguish itself from sibling tools like list_ticket_provider_effects or check_ticket_provider_status, but the resource is clear enough for an agent to identify the tool's core function.

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 clear context: it is a read of retained/historical observations, optionally scoped by ticket or provider, and explicitly notes that historical checks are not proof of current remote state. It does not name alternative tools or give explicit when-not conditions, so it stops short of a 5.

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