Cherry pick commit

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the safety profile is largely covered. The description adds genuinely useful return behavior ('wrapper containing the original response and a Commit model') and an error case, but says nothing about the non-idempotent side effect — repeated calls creating multiple branches — or what 'into a new branch' means concretely (start_branch vs ref).

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 purpose statement is correctly front-loaded, but the rest is autogenerated docstring scaffolding: a '**kwargs' Args line that conveys nothing about the real 40-param surface, plus generic Returns/Raises boilerplate. Little of the text earns its 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?

For a 40-parameter, non-idempotent mutation with no output schema, the description should at minimum identify the required project_id and the commit/target-branch params, and explain what the cherry-pick creates. None of that is present, leaving the agent to guess from bare parameter names.

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% across 40 parameters, so the description must carry the whole burden, and it does not: the only parameter text is '**kwargs: Additional parameters for the request,' which is boilerplate and actively misleading given 40 explicitly named properties. The parameters that determine correctness — commit_hash, branch/ref, start_branch, start_project — are never mentioned.

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 first sentence gives a specific verb and resource — 'Cherry-pick a commit into a new branch' — which is clearly a GitLab commit operation. It does not, however, distinguish itself from nearby siblings such as gitlab_revert_commit or gitlab_create_commit, leaving the agent to infer the difference.

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 over gitlab_revert_commit or gitlab_create_commit, nor on prerequisites (project_id is required; commit_hash/branch/ref appear to be needed but are unstated). The only usage-adjacent sentence is an error note about ParameterError.

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