Get Pull Request Activity

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds behavioral context beyond annotations: pagination defaults, the warning threshold for >10 pages or 300 items, the event types returned, and comment resolution fields. It does not detail auth requirements, but with annotations present this is a solid disclosure.

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 front-loaded with the purpose and then uses clear Args, Returns, and Note sections. The Returns section is detailed and somewhat redundant with the output schema, but it remains structured and readable; most sentences earn their place.

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?

Although an output schema exists, the description is complete enough for correct invocation: it documents all parameters, pagination behavior, warning thresholds, event types, and comment resolution metadata. It also clarifies the historical nature of the log versus current review status.

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 carries the full burden for five parameters. It does so well: repo_slug, pull_request_id, workspace default, page_size default and recommended max, and max_pages default and recommended max are all explained in the Args section.

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 opening sentence states a specific verb and resource: get the activity log for a pull request, with pagination. The Returns section further clarifies that this is historical activity (update/comment/approval/changes_requested), and the Note distinguishes current review status as coming from get_pull_request, so the agent can separate this from sibling PR-read tools.

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 gives clear usage context by explaining that this returns history and that current review status should come from get_pull_request instead. It also warns about fetching more than 10 pages or 300 items. It does not explicitly compare against get_pull_request_comments or get_pull_request_statuses, so it stops short of full alternative routing.

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