get_work_packages

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

With no annotations provided, the description carries the full burden and does well: it mentions parallel fetching, per-item failure reporting without stopping the batch, deduplication of IDs, and that id/success/error fields are always included. It also warns about size limits and redirection to a file for large batches. Minor gaps like auth requirements or rate limits are not covered, but for having no annotations, this is strong.

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 well-structured with a leading summary, followed by behavior, parameters, and a warning. Every sentence adds value—no fluff. It front-loads the core purpose and then details constraints and pitfalls. The paragraph breaks improve readability. This is efficient and thorough without being verbose.

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?

Given no output schema, the description explains what results look like (per-item success/error, id/success/error always included), which is important. However, it lacks details on the exact structure of returned items beyond the always-included fields, error handling specifics beyond 'reported individually', and does not clarify whether text_limit applies to select fields. As a tool that returns batch results, this is a minor gap.

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 0%, so the description must fully explain parameters. It explains 'ids' (accepts internal or display IDs, not UI numbers, deduplicated), 'select' (restricts fields, invalid names return allowed set), and 'text_limit' (mentioned as a mitigation for large batches). However, the text_limit description is sparse and lacks specifics on what it limits (e.g., character count per field) and how it interacts with select.

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 clearly states 'Get multiple work packages by ID in a single batch call', specifying the verb (get), resource (work packages), and scope (batch). It distinguishes from sibling tools like get_work_package (singular) and list_work_packages (list semantics) by emphasizing batch retrieval.

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 description explicitly states when to use this tool ('Get multiple... by ID in a single batch call') and provides critical usage guidance such as maximum 100 IDs per batch, ID formats (internal vs display, not UI numbers), and a warning about large batches. It implies this is for known IDs, contrasting with search/list tools, but does not name alternatives explicitly. The detailed constraints and the proactive advice about text_limit/select give clear usage context.

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