create_merge_request_note

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

The description discloses several important behavioral aspects that go beyond the single annotation `openWorldHint: true`. It notes that the operation 'changes remote GitLab state', which implies it is not a read-only operation, and it warns that GitLab returns validation, conflict, permission, or rate-limit errors instead of silently applying an invalid request. It also mentions required permissions ('requires the necessary project or group permission'). The annotation `openWorldHint` is vague, but the description adds concrete behavioral transparency about state change and error handling. There is no contradiction; the description does not contradict the annotation.

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 paragraph of moderate length, but it is dense with useful information. It front-loads the primary purpose ('Add a new note to a merge request') and then provides usage, behavior, and parameter guidance. There is no redundancy; every sentence contributes to the agent's understanding. It loses one point because it is not as tightly structured as a two-sentence description could be, and it mixes several pieces of guidance in one run-on sentence, but it remains efficient.

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 only three parameters, all required, with 100% schema coverage, and no output schema, the description covers the essential usage, behavior, and parameter directives. It does not explicitly state the return value (e.g., the created note object), but since there is no output schema, the description could have mentioned that it returns the note, but it does not. However, the description is sufficient for an agent to call the tool correctly: it knows what it does, when to use it, what parameters to provide, and what errors to expect. The lack of return-type disclosure is a minor gap, but the overall completeness is high.

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 description adds meaningful parameter guidance beyond the schema. For `project_id` and `group_id`, it explicitly instructs to 'provide the numeric ID or complete URL-encoded path described by the schema', which reinforces the schema but adds usage nuance. It also says 'use required identifiers and pagination fields exactly as documented,' adding a caution. However, the description doesn't explain the meaning of each parameter beyond what the schema already says (e.g., `body` is the content, `merge_request_iid` is the IID). Given that schema coverage is 100%, the description supplements it with usage directives, so a score of 4 is appropriate.

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 ('Add') and resource ('new note to a merge request'), which distinguishes it from update/edit tools that modify an existing resource. It also explicitly names its sibling purpose by pointing to the 'update or edit tool when the resource already exists.' However, the distinction from `create_merge_request_note` versus `create_merge_request_discussion_note` or `create_draft_note` is not directly addressed, though the 'new note' language and the mention of `merge_request_iid` suggest a direct note rather than a thread or draft.

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 provides explicit when-to-use guidance: 'Use this for a new resource or action; choose the corresponding update or edit tool when the resource already exists.' This clearly routes the agent away from update scenarios, but it does not explicitly list alternative tools (like `create_merge_request_discussion_note` or `create_draft_note`) where a note might also be created. The guidance is clear but not exhaustive regarding sibling alternatives, so it earns a 4 rather than a 5.

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