Get work package git activity

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

Even with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false already present, the description adds crucial behavioral context: the distinction between internal `id` and human-facing `number`, the fact that 'closed' does not imply 'merged', and the error-handling behavior where 403/404s are reported in `notes` instead of being raised. It also discloses that links are only created via text mentions in commit messages or MR/PR descriptions, not by the API.

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 long but deliberately structured: purpose, use cases, return shape, availability semantics, pitfalls, and cross-references. Every sentence carries weight—none are filler. The critical warnings (id vs number, closed vs merged, notes for errors) are essential for correct invocation and interpretation. It front-loads the purpose and then layers details logically.

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 the tool's complexity (multiple source types, availability flags, CI status, pitfalls), the description covers every operational aspect: what data comes back, what each field means, how errors surface, and how links are created. It also points to companion tools for deeper detail, and the output schema covers the exact return shape. There is no obvious gap that would leave an agent guessing.

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?

The schema already describes both parameters with 100% coverage. The description goes further by explaining the concurrency behavior of `include` ('they are fetched concurrently, so narrowing this saves little') and the fact that availability is always reported for all three sources regardless. It also strongly advises against guessing `work_package_id` and tells the agent where it comes from, adding trust and safety guidance.

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 opens with a specific and vivid statement: 'Show the code behind a work package: commits, pull/merge requests and CI status.' It clearly names the resource (work package) and the action (show git activity), and enumerates the three concrete result categories. This unambiguously distinguishes it from siblings like get_work_package or list_work_package_comments.

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?

Explicitly prescribes when to use the tool: 'Use this for "is this ticket implemented", "what shipped for it", "did CI pass", "which branch/PR is this in".' It also names alternatives and cross-references: full PR detail via get_github_pull_request, the ticket via get_work_package, and the discussion via list_work_package_comments. This gives the agent clear decision criteria.

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