Manage tag

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

The annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation and destructive nature are covered. The description adds useful domain behavior beyond annotations: 'On-hold tags block next actions.' It does not contradict the annotations.

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 two sentences with no fluff and the main operation is front-loaded. The second sentence adds domain context but is not integrated with the parameter schema; still, every sentence earns its place and nothing is redundant.

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 nine parameters, zero schema descriptions, and no output-schema details, this description is far from complete. An agent cannot determine which parameters are required for add vs edit vs remove, which identifier to use (tag_id vs tag_name), or how nesting and on-hold status are set. The output schema exists, so return values need no explanation, but the call semantics remain under-specified.

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 carries the full burden for explaining parameters, but it only loosely maps verbs to the action enum and never clarifies the roles of tag_id, tag_name, new_name, parent_tag_id, parent_tag_name, allows_next_action, or status. 'On-hold tags block next actions' hints at status/allows_next_action but does not specify how to set them.

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 specific verbs ('Create, rename, nest, or delete') tied to a clear resource ('a tag'), making the tool's purpose immediately evident. It differentiates from sibling tools like query_tags, manage_folder, and manage_perspective by naming the exact tag operations it performs.

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 implied by the mutation verbs and tag resource, but the description gives no explicit guidance about when to choose this tool over query_tags for reading tags or manage_folder for hierarchical management. No alternatives or exclusions are mentioned, so the agent must infer context from sibling names.

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