Get commit statuses

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds limited context by noting that the response is a wrapper containing Status models and that invalid parameters raise ParameterError, but it does not explain pagination, filtering behavior, or the meaning of the many status-related parameters.

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 text is short and front-loads the core purpose, but it is severely under-specified for a 40-parameter tool. The Args section is boilerplate ('**kwargs') and does not earn its place, while critical invocation guidance is absent.

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?

For a tool with 40 parameters, no schema descriptions, and no output schema, the description is far too thin. It names only the return wrapper and invalid-parameter error, leaving the agent without enough information to select or invoke the tool correctly.

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 has 40 parameters with 0% description coverage, and the description provides only a generic '**kwargs: Additional parameters' note. It adds no meaning for required or optional parameters such as project_id, ref, state, name, or pagination fields, so an agent cannot infer parameter semantics from the definition.

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 states a specific verb and resource: get statuses of a commit. It is clear enough to distinguish from most CRUD siblings, but it does not differentiate this from closely related commit tools such as gitlab_get_commit or gitlab_post_build_status_to_commit.

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 use this tool versus alternatives, no prerequisites, and no exclusions. The description merely restates the operation, leaving an agent to infer its place among many commit- and pipeline-related siblings.

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