github_list_contributors

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

No annotations are provided, so the description carries full burden. It doesn't mention whether this returns commit counts sorted, whether pagination exists beyond max_results, what the output format looks like, or whether it requires authentication/permissions. The mention of 'commit counts' adds some value but leaves significant gaps.

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 compact in an Args-style format, but it mostly restates parameter names from the schema. The single functional sentence 'List repository contributors with commit counts' is efficient, but the Args block adds little value and could be trimmed or enriched.

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 an output schema present, return values may be documented there. However, the tool's purpose is simple enough that 0% schema coverage for 4 params is a real gap. The description doesn't explain max_results semantics fully (does it truncate? sort?), session behavior, or error cases. A bit more context would improve completeness for a list-style tool.

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%, and the description repeats parameter names with minimal elaboration. It adds 'default: 30' for max_results which mirrors the schema's default. It doesn't clarify the session_name semantics beyond 'GitHub session to use', which adds little beyond the schema. With 4 params at 0% coverage, the description should compensate more.

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 'List repository contributors with commit counts' with a specific verb+resource. The purpose is distinct from siblings like list_repos or list_branches, though it doesn't explicitly differentiate itself from other list operations.

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?

No guidance on when to use this tool vs alternatives is provided. There's no mention of when contributors would be needed, no exclusions, and no indication of alternatives for related data (e.g., list_repos vs contributors).

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