update_term

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

With no annotations provided, the description carries the full burden and does real work: it discloses the authentication requirement ('API token authentication'), the critical partial-update semantic ('omitting aiMetadata leaves existing AI fields unchanged'), version tracking, and term group relation management. This is meaningful behavioral context beyond a bare mutation statement, though it stops short of clarifying response format, permissions, or merge behavior for non-AI fields.

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?

Four sentences with no filler: the primary action is front-loaded, the critical aiMetadata warning is isolated with IMPORTANT, and the capability summary is compact. Each sentence earns its place; only 'using API token authentication' is slightly redundant with general API tool expectations.

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 tool with a complex nested aiMetadata schema and conditional requirements, the description covers the highest-risk behavior (partial updates and recommended AI fields) and mentions version tracking. But with no annotations and no output schema, it leaves gaps: it does not state what happens to omitted non-AI fields (merge vs. replace), whether special permissions are needed, or what the response contains.

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 high (all 8 parameters have descriptions, including nested aiMetadata properties), so the baseline is 3. The description adds genuine value above the schema by advising when to send aiMetadata, which fields to include (ai_generated=true, ai_model, ai_generation_date), and by referencing version tracking and term group relations, which maps to ai_version and term_group_id semantics.

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: 'Update an existing individual term', which clearly identifies the operation and distinguishes it from creation tools like create_term. However, the sibling list includes a generic 'update' tool, and the description does not clarify how update_term differs from it, so it falls short of full sibling differentiation.

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 phrase 'existing individual term' implies this tool modifies an already-created term rather than creating one, giving some usage context. However, the description never names alternative tools (create_term, find_existing_skill_terms) or states explicit conditions for when to prefer them, leaving the choice mostly implied.

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