edit_thread

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 disclose key behavioral traits: partial updates ('Only provided fields are updated; omitted fields are left unchanged'), content format requirement ('Ed XML format'), and category validation via list_categories. It stops short of mentioning permission/error behavior, but the disclosed behaviors are significant for correct invocation.

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 followed by a structured Args block. Every line adds value, and the format makes the parameter behaviors easy to scan without wasted words.

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 mutation tool with five parameters and no annotations, the description covers partial-update behavior, content format, valid category sources, and thread_id prerequisites. An output schema exists, so explanations of return values are unnecessary; this is a complete, self-sufficient description.

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 Args section comprehensively explains each parameter beyond the schema: thread_id is sourced from list_threads/search_threads, optional fields are described as 'omit to keep current,' and content must be in Ed XML format. This fully compensates for the 0% schema description coverage.

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 'Edit an existing thread's title, content, or category,' which gives a specific action, resource, and affected fields. This clearly distinguishes it from sibling tools like delete_thread or lock_thread, and the resource 'thread' separates it from edit_comment.

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 provides clear context for when to use the tool: editing an existing thread, with thread_id obtained from list_threads or search_threads. It does not explicitly state alternatives or exclusions (e.g., 'use edit_comment for comments'), but the focus on threads is unambiguous enough for typical usage.

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