Post a comment on a Bitbucket pull request, either top-level or as a threaded reply by supplying an existing comment ID.
Post a comment on a pull request. Pass parentId to thread the comment as a reply under an existing comment; omit it for a top-level comment.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| repo | Yes | Repository slug, e.g. sigma-skills | |
| text | Yes | ||
| project | Yes | Bitbucket project key, e.g. KD_SIGMA | |
| parentId | No |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full behavioral burden. It does disclose the threading/reply behavior, which is genuine value, but for a write operation it says nothing about required permissions or scopes, whether the comment body supports markdown, whether edits/deletes are possible afterwards, or what happens on failure — all material for a mutating call.
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?
Two tight sentences, front-loaded with the action and then the one branching behavior an agent needs. Nothing repeats the name or the title, and nothing could be cut without losing information.
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?
This is a write tool with no annotations, no output schema, 40% parameter coverage, and an undocumented required 'id' whose meaning the agent must guess. Given that combination, the description should do more than explain threading — at minimum it should identify what 'id' refers to and what a successful call returns or affects.
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 coverage is only 40%, and the description compensates well for the one genuinely ambiguous optional parameter, explaining exactly what parentId does and what omitting it means. However, the bare 'id' parameter is left unexplained, and it is genuinely ambiguous here since a comment-posting tool could be taking a pull request id or a comment id; 'text' likewise has no note on formatting. Partial compensation for a coverage 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?
"Post a comment on a pull request" names a specific verb (post) and resource (comment on a pull request), which cleanly separates it from the read-oriented siblings (bitbucket_list_pull_requests, bitbucket_get_pull_request, bitbucket_get_activities). It doesn't explicitly contrast itself with any sibling, and no sibling is a near-duplicate writer, so the omission is minor.
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 gives real conditional guidance, but only for the parentId parameter: include it to reply under an existing comment, omit it for top-level. There is no guidance on when to reach for this tool at all, no prerequisites, and no mention of alternatives such as resolve_task for the comment-like task workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.