update_tag

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

Annotations already establish mutability (readOnlyHint=false) and non-destructiveness (destructiveHint=false). The description adds useful behavioral detail beyond annotations, including the error condition for a missing tag, the optional nature of the updates, and the hex format requirement for color with no leading '#'.

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 concise and well-structured: a one-sentence purpose statement followed by two bullet-style lines covering invocation and error behavior. Every sentence earns its place with no redundancy or filler.

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 update tool with clear schema annotations and no output schema, the description provides the essential invocation details: required identifier, optional fields, and failure behavior. It does not describe the return value, but that is not critical for correct selection and invocation.

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 covers all parameters with 100% description coverage, so the baseline is 3. The description adds extra semantic value by clarifying that 'tagName' identifies the existing tag and that 'name'/'color' are optional updates, plus the specific hex format nuance of no leading '#'.

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 uses a specific verb ('update') with a clear resource ('a tag in your SimpleLocalize project'). It also implies the existing tag must be identified by 'tagName', which clearly distinguishes it from sibling tools like create_tag, delete_tag, and get_tags.

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 clear usage context: provide the existing 'tagName' and optionally update 'name' and/or 'color'. It also notes that an error is thrown if the tag does not exist, effectively communicating that this is for existing tags only. It does not explicitly name alternatives, but the intended use is unambiguous.

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