update_related_item

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

With no annotations, the description carries the disclosure burden. It truthfully indicates a mutating operation, limits the mutation to notes, and states the return type. It does not mention permissions, whether existing notes are fully replaced, or failure behavior, so transparency is adequate but thin.

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 short, front-loaded with purpose, and uses a clean Args/Returns structure. No sentence is wasted.

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?

The description plus input schema can support a straightforward call, and the returned JSON string is noted. But a caller is left guessing valid source_type values and how the source/related-item identifiers relate, which is material for this endpoint. It is adequate but not complete for an agent without domain knowledge.

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 0%, but the description supplies a line for every parameter: source_type, source_id, related_item_id, and notes. These one-line definitions clarify role, especially notes as 'New notes for the relationship.' They are still high-level and omit allowed source_type values, so not full semantic richness.

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?

States a specific verb and resource: 'Update a related item.' It further scopes the operation with '(currently only notes can be updated),' and the notes parameter clearly defines what is changed. This differentiates it from create_related_item, delete_related_items, and list_related_items.

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 implies use when you need to change a relationship's notes and warns that only notes can currently be updated. However, it does not name alternatives such as create_related_item or delete_related_items, nor state when those would be preferred. The guidance is implicit rather than explicit.

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