Creates a named tag with an optional hex color, returning 201 for new tags and 200 if the name already exists.
Create a tag. Idempotent on name: 201 when created, 200 when it already existed (colour unchanged).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| color | No | #5046E5 |
Changes observed during successful MCP inspections.
v0.2.2Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states "Idempotent on name", but the annotations declare idempotentHint=false. That is a direct conflict about whether a repeated call has additional effect, which is exactly the question an agent needs answered before retrying. The status-code detail (201 vs 200) and the colour-unchanged rule are genuinely valuable, but they are undermined by contradicting the structured metadata.
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 short sentences, zero filler, with the operation stated first and the idempotency/status-code behaviour immediately after. Nothing needs trimming.
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 simple two-parameter create tool with no output schema, the description usefully explains both return paths (201/200), which is what an agent needs to interpret a result. However, the idempotency conflict with annotations leaves the retry-safety question ambiguous, and nothing is said about permissions or what the returned tag looks like.
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%, so the description must carry parameter meaning, and it does add real semantics: name is the identity key for idempotency, and colour is only applied on first creation ("colour unchanged" on the 200 path). It still omits the colour format/default (#5046E5, hex pattern) and the name length bounds, so it only partially compensates.
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 opens with a specific verb and resource ("Create a tag"), which unambiguously separates it from the sibling read/delete/link operations (list_tags, delete_tag, tag_contact). An agent can identify the operation without opening the schema.
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?
Usage is only implied: the tool is the way to mint a tag before it can be attached via tag_contact. There is no explicit when-to-use/when-not, no statement about prerequisites (e.g. whether the tag must not already exist), and no named alternative for the 'tag already exists' case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.