github_compare_commits

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds genuine context: the authority-routing constraint, that Spring verifies the effect field, and that effect is required and must be read. However, the approval_ref line—'when resuming a write'—is disorienting for a read-only, effect=read tool and mildly blurs the behavioral picture, though it does not rise to a full contradiction.

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 structure is clean and front-loaded: an identity line, a one-sentence routing constraint, then a labeled Args list. At roughly the right size for seven parameters, every line carries information. Minor waste: the opening sentence duplicates the tool name that already appears in the tool name field.

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?

Output schema and annotations cover return values and safety, and all wrapper parameters are documented. But an agent attempting to actually compare commits cannot determine what to place inside the `arguments` JSON string (base/head refs, repository, options), and there is no guidance distinguishing this from github_list_commits. Adequate for a generic connector wrapper, but the operation's core payload semantics are absent.

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?

With 0% schema description coverage, the description carries the full burden and responds by glossing all seven wrapper parameters with meaningful labels ('Authenticated Project UUID,' 'Stable business-action identity,' 'Spring verifies it'). This adds real value the schema lacks. The notable gap is the `arguments` parameter—'JSON string of arguments for the connector operation'—whose inner payload is never specified, leaving the actual compare-operation semantics opaque.

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 by restating the name—'Github connector operation compare_commits (platform tool github.compare_commits)'—which is effectively a tautology. It never explains what comparing commits means (e.g., diffing two refs), what inputs the underlying operation requires, or what the result contains. Nothing distinguishes it from siblings like github_list_commits or github_get_pull_request beyond the name itself.

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?

There is no guidance on when to select this tool versus alternatives. The only contextual statement, 'Routes only through the exact project/account governed connector authority,' describes routing constraints, not usage selection. No exclusions, prerequisites, or alternative sibling tools are referenced.

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