update_document_section

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

No annotations are provided, so the description must disclose behavior. It states the tool updates content (a write operation), which implies a mutation. However, it does not describe side effects, permission requirements, idempotency, or whether changes are reversible. The description is minimal, leaving the agent to infer basic mutation behavior.

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 highly concise: three sentences with zero waste. The first sentence states the primary function, the second provides a prerequisite, and the third gives a post-action instruction. It is front-loaded with the core purpose, making it easy for an agent to parse quickly.

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 no output schema, the description adequately covers the essential workflow: what the tool does, how to get input parameters, and what to do after. It does not describe the return value or error cases, but for a simple update operation, this is reasonable. The description is complete enough for an agent to use the tool correctly in context.

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?

Parameter schema covers 100% of parameters with descriptions (e.g., document_id, section_id, content). The description adds context beyond the schema by instructing how to obtain section_id (via list_document_sections) and the follow-up action (publish_document). This adds meaningful value, though it does not elaborate on format constraints or defaults.

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?

Description clearly states the action (update), resource (existing IT Glue document section), and scope (content). It distinguishes from siblings by referencing list_document_sections and publish_document, providing a clear workflow. The verb 'Update' is specific and matches the tool name, reducing ambiguity.

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?

Explicitly tells when to use (to update content) and provides step-by-step guidance: use list_document_sections to get section IDs, then call publish_document after editing. This helps the agent understand the sequence. However, it does not explicitly state when not to use or mention alternatives, but the workflow guidance is strong.

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