haops_update_doc_section

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

With no annotations, the description carries full burden. It discloses that slug must be unique among siblings (409 on collision), that it cannot address a section with empty slug, and that verbose flag alters response. It does not explicitly state that updates are overwrites or mention permissions, but the behavioral traits are largely covered.

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?

Two sentences plus an 'IMPORTANT' note—front-loaded with purpose, then critical usage detail. No wasted words. Every sentence adds essential information.

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 8 parameters, 3 required, and no output schema, the description sufficiently covers how to identify the section (projectSlug, artifactSlug, sectionSlug), what can be updated, and the verbose option. It lacks details about the default compact summary and error handling beyond slug collision, but overall it is adequate for agent invocation.

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 100%, so baseline is 3. The main description adds value by emphasizing the artifactSlug kebab-case rule and the slug uniqueness constraint, but these are also present in the schema descriptions. The additional emphasis does not significantly elevate the score beyond baseline.

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 verb (update) and resource (documentation section) and lists the fields that can be updated (content, title, slug, source hint). It also immediately distinguishes this tool from other update-* tools by noting the use of artifactSlug (kebab-case) instead of UUID, making its purpose specific and differentiating it from siblings.

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?

Description explicitly warns about the identifier exception ('Uses artifactSlug — NOT the artifact UUID. This is an exception: most other update-* tools use UUID identifiers.') and advises using haops_list_doc_artifacts to find the slug. This provides clear context for when to use this tool. However, it does not mention when not to use it (e.g., for updating other entities) or provide explicit alternatives.

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