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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds behavior annotations cannot express: default filtering to open (non-done) issues unless include_done is true, cursor pagination, the returned item shape with project_key/project_name, Sales & Billing installment inclusion with flags, and the agent-token (agt_) assignment semantics.

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?

Sentences are dense and front-loaded, leading with the headline behavior and the alternative tool. The main inefficiency is the first sentence restating the title verbatim and the triple-nested D-reference parentheticals, which cost space without adding selection value.

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, but the description enumerates the returned fields, the added project_key/project_name, pagination via next_cursor, and the installment flags — everything an agent needs to consume the result correctly. Defaults and the agent-account edge case are also covered.

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% (limit and include_done have no schema descriptions), but the description compensates for include_done ('Open issues only ... unless include_done: true') and explains cursor/next_cursor pagination. The limit parameter's meaning and its 50/200 bounds are left entirely to the schema, so it falls short of 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?

The description names a specific verb+resource (list open issues assigned to you), states cross-project scope, ordering, and the Sales & Billing installment extension. It also explicitly differentiates from search_issues and get_issue, so an agent can pick it out from 70+ siblings without opening the 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?

It states when to use it ('What's on my plate?') and when not to: use search_issues when the user means one project or needs other filters, and call get_issue before changing any listed issue. Exclusions and the pre-mutation step are both explicit.

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