get_collaborator_permission

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

With no annotations provided, the description carries the full burden of behavioral disclosure. The description states this is a read/check operation ('Checks whether') which implies non-destructive behavior, but does not disclose what happens for missing users, whether both owner and non-owner paths work, authentication prerequisites, or how permission values are returned. The output schema exists and may cover return format, but edge-case behavior is undisclosed.

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 a single concise sentence that front-loads the core purpose. There is no wasted text. However, it is so brief that it sacrifices useful behavioral detail; the conciseness is appropriate but slightly under-elaborated.

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 that the tool has 3 parameters with a default-bearing optional parameter (owner), zero annotation coverage, and sits among 16 sibling tools where disambiguation is important, the description is under-specified. It does not explain the owner/repo distinction, how the caller should construct the repository reference, or what permission values are possible. The output schema may cover return structure, but invocation prerequisites are missing.

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 names one parameter semantically ('user/bot') but does not clarify the distinction between 'owner' (which has a default of empty string) and 'repo', nor how 'username' differs from 'owner'. The description does not compensate for the schema's bare parameter names. For a 3-parameter tool with zero description coverage, this is a notable gap.

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 the verb ('Checks whether'), the resource ('user/bot is a collaborator'), and the outcome ('returns repository permission'). It distinguishes itself from sibling tools that inspect repositories or lists, as none of the siblings seem to check collaborator permissions. Clear enough for an agent to identify when this tool is relevant.

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 states what it does but provides no guidance on when to use it versus alternatives. Among 16 sibling tools focused on repositories, PRs, and workflows, there is no explicit context about when collaborator permission checking is preferred over get_repository or healthcheck for precondition checks. No when-not-to-use or alternative suggestions are given.

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