Get issue elements

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds genuine behavioral detail beyond that: it enumerates the return shape and, importantly, shows that unresolved elements come back as `{guid, missing: true}` rather than being omitted — a trait an agent could not infer from the annotations. It stops short of noting pagination or the 1000-issue cap behavior.

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?

Purpose is front-loaded in the first clause, followed by output shape and routing. Very little waste, though the dense inline output grammar in the middle sentence sacrifices some readability for compression — justified since no output schema exists.

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?

With no output schema, the description correctly compensates by specifying the return structure, and both parameters are fully documented in the schema. Remaining gaps are minor: nothing about permission requirements, the 1000-issue limit, or how nonexistent issue names are handled.

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 100%, so the baseline is 3. The phrase "by attachment type" loosely mirrors the `types` parameter and its default, but the schema's enum descriptions already explain Highlight/Creation/Deletion/Modification far more fully, so the description adds no real semantic value on parameters.

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 ("Returns") and resource ("elements attached to issues") with a scoping qualifier ("by attachment type") that separates it from get_issues (issue metadata) and attach/detach_elements_to_issue (mutations). An agent can identify the read-only, per-issue element lookup 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?

The final sentence routes the agent forward ("Pass the GUIDs to get_element_details, select_elements or zoom tools"), which is useful chaining advice, but it never states when to choose this tool over siblings like get_issues or get_element_details, nor any exclusions or prerequisites. Usage is implied by the purpose rather than articulated.

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