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

No annotations are provided, so the description carries the full disclosure burden. It says nothing about permissions required, whether the book is immediately visible/searchable, or that supplying tags replaces existing tags (that fact lives only in the schema). The one behavioral clue is that shelf placement is optional.

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?

A single short sentence with zero padding and the primary action front-loaded. It is efficient, though the brevity edges toward under-specification for a four-parameter mutation tool.

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 no annotations and no output schema, the description is too thin: it omits required fields, the tags replacement behavior, and any note on what is returned. An agent can call it, but only by leaning almost entirely on the schema.

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 description coverage is 75%, so the schema already documents shelf_id, tags, and description reasonably well. The description's only parameter-relevant addition is "optionally placing it on a shelf," which merely restates the shelf_id schema note rather than adding format or constraint detail.

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 ("Create a book") and adds a scope note about optional shelf placement. It does not distinguish itself from sibling creation tools like create_chapter, create_page, or create_shelf, so an agent gets no routing help, but the core action is unambiguous.

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 "optionally placing it on a shelf" hints that shelf_id is optional, but there is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives among the many sibling creation tools. The agent must infer usage entirely.

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

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

With no annotations provided, the description carries the full burden and largely doesn't: it says nothing about permissions, whether creation requires an existing book, what happens on duplicate names, or what the response looks like. The one useful behavioral fact is the non-nesting constraint, which is a real but small contribution for a mutation tool.

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 short sentences, purpose first and the caveat second, with no filler or restated boilerplate. Appropriate size for the tool.

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?

A mutation tool with no annotations, no output schema, and a 50%-documented schema needs more than two lines. Missing prerequisites, side effects, and parameter meaning leave the agent under-informed for a create operation.

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 description coverage is only 50% (tags and description documented, name and book_id not), so the description is the place to compensate — but it mentions no parameters at all. It only implies via 'in a book' that a book_id is needed; the required name and the tag-replacement semantics go unexplained.

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 ('Create a chapter in a book') and adds a domain fact — chapters group pages and can't be nested — that helps distinguish it from create_page/create_book/create_shelf. It never names those siblings explicitly, so differentiation is implied rather than stated.

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?

No when-to-use guidance, no alternatives named, and no prerequisites (e.g. that book_id must reference an existing book) beyond the bare 'you can't nest chapters' constraint. The agent must infer placement from the sibling list.

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

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

With no annotations, the description carries the full burden for a mutation tool. It usefully discloses the duplication risk, but says nothing about required permissions, reversibility, or what happens when placement params conflict — schema covers that last point, yet auth and failure behavior remain undisclosed.

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 tight sentences: the create action and destination are front-loaded, then the dedup advice. No filler or redundancy; every clause earns its place.

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 5-param mutation tool with no annotations and no output schema, the description covers purpose, placement, and the dedup caution but omits permissions, return shape, and error behavior. It is adequate but leaves real gaps an agent would need before calling confidently.

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 description coverage is 80%, so the schema already explains book_id, chapter_id, markdown, and tags. The description's 'inside a chapter (chapter_id) or directly in a book (book_id)' largely restates the schema's placement semantics without adding format or precedence detail beyond it. Baseline 3 applies when the schema does the heavy lifting.

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 ('Create a page') plus the input format ('from Markdown') and where it lands (chapter_id or book_id), which implicitly separates it from create_book/create_chapter/create_shelf. It never names a sibling explicitly, so differentiation is by resource name rather than a direct contrast.

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?

Gives a concrete precondition: 'Check first that a page on this topic doesn't already exist — updating beats duplicating,' which routes the agent toward update_page over create. It stops short of naming the tool (search/update_page) to use for that check, so the workflow link is implied rather than explicit.

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

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

With no annotations provided, the description carries the full behavioral burden, and it discloses almost nothing: no permission requirements, no uniqueness/duplicate handling for the name, no side effects, and no mention of what creation returns. The parenthetical defining a shelf adds conceptual clarity but not behavioral context.

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?

A single short sentence that front-loads the action and resource, with zero filler. It is efficient, though arguably terse to the point of under-specification rather than optimally structured.

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 4-parameter mutation tool with no annotations and no output schema, the description is too thin: it omits return values, error/duplicate behavior, and any creation constraints. The richer schema details (tag replacement, ordering) partially compensate but the description itself leaves meaningful gaps.

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 description coverage is 75%, so most parameters (tags, book_ids, description) are already documented in the schema, including the ordering and tag-replacement semantics. The description only loosely echoes book_ids with 'optionally with books on it' and adds nothing about name, tags, or description beyond what the schema states.

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 ('Create a shelf') and clarifies the domain concept with a parenthetical ('a group of books'), plus notes the optional book attachment. This distinguishes it from sibling create_* tools (create_page, create_book, create_chapter) by resource, though it does not explicitly contrast with them.

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?

There is no guidance on when to use this versus alternatives (e.g., update, create_book) and no stated prerequisites or preconditions. The only hint is the phrase 'optionally with books on it', which implies the book_ids path but is not framed as usage guidance.

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

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

destructiveHint=true already flags danger, but the description adds non-obvious behavior: this is a soft delete into a recycle bin that an admin can restore, and it details cascade semantics per type (book/chapter delete contents; shelf preserves books). That is exactly the context an agent needs before invoking a destructive operation.

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?

Three sentences, no filler, and the most decision-relevant facts (recycle bin, restorable, cascade rules) come before the usage caveat. Every sentence earns its place.

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?

With no output schema and only a destructiveHint annotation, the description supplies what is missing: reversibility, cascade scope per type, and a gating condition for invoking it. Nothing an agent needs to call this safely is absent.

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 description coverage is 0%, so the description must carry the load. It does explain the behavioral meaning of each `type` value through the cascade rules, adding real value over the bare enum, but the `id` parameter's expected value/format is never addressed.

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 ('Move a page, chapter, book or shelf to the BookStack recycle bin') rather than the generic name/title. It also names the exact object types accepted, so an agent can distinguish it from create_*/update_* siblings without opening the schema.

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?

Gives an explicit when-to-use constraint: 'Only delete when the user explicitly asked for it,' which is strong safety guidance for a destructive tool. It does not name an alternative (e.g., update or a soft-archive sibling), so it falls short of full when/when-not/alternatives routing.

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

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

With no annotations, the description carries the full burden and does disclose the critical behavioral constraint that old_text must match the source exactly, plus the Markdown-editor-only restriction. It does not cover failure behavior (e.g. what happens when no match is found), permissions, or reversibility, which keeps it short of a 5.

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 dense sentences, zero filler. The core behavior is front-loaded, and the constraint/routing information follows in a compact clause chain.

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 four-parameter mutation tool with no output schema and no annotations, the description covers the mechanism, the exact-match requirement, and the sibling routing needed to call it correctly. It stops short of describing error outcomes (no match, multiple matches) and permissions, leaving a modest gap.

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 75% and the schema already documents old_text ('exact text to find, including whitespace and Markdown syntax'), new_text (empty deletes), and replace_all (default false). The description reinforces the exact-match semantics of old_text but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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+resource ('Exact find-and-replace in a page's Markdown source') with the mechanism and the value proposition ('cheap way to fix or extend part of a page without resending all of it'). It explicitly distinguishes itself from the closest sibling, update_page, by editor type.

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?

Gives an explicit alternative and the condition that selects it: 'Only for Markdown-editor pages; for WYSIWYG pages use update_page.' It also prescribes the prerequisite workflow ('read the page with get first'), leaving nothing to inference.

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

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

With only readOnlyHint=true declared, the description carries most of the behavioral burden, and it does disclose the shape of the result per type (Markdown content + location for pages, chapter/page TOC for books, etc.). It stops short of covering error cases (invalid id, missing item) or permissions.

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 short clauses, zero filler, front-loaded with the core action and then the per-type return mapping. Every sentence earns its place.

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?

No output schema exists, and the description compensates by spelling out the return shape for each type. What remains missing (error behavior, permission/visibility constraints) is minor for a single-item read.

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%, so the description must explain the parameters, and it does give real meaning to every 'type' enum value (page/book/chapter/shelf) and clarifies that 'id' selects one specific item. It says nothing about id formatting or scope/visibility limits.

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 (open one item) plus the resource (BookStack item) and enumerates what 'item' means per type. It is clearly distinguishable from search/list/create/update/delete siblings by implication, though it never names an alternative explicitly.

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?

Usage is implied: fetch a single known item by id, as opposed to search or list. No explicit when-to-use/when-not guidance and no alternative tool is named, so the agent must infer the boundary from the sibling names.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that listing returns existence-style results rather than contents and hints at sort behavior, but says nothing about pagination (count/offset) or return shape, which matters for a 6-param list tool.

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?

Three tight sentences, front-loaded with the resource scope, then usage, then the alternative. No filler or repetition.

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 a read-only list tool with no output schema and 6 parameters, the description adequately covers purpose, use cases, and the get-vs-list distinction. Its only real gap is pagination/return behavior, which is a minor omission for a listing endpoint.

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 50%, so the description must carry some weight: it enumerates the type enum values inline and demonstrates the sort parameter ('sort=updated'). However, it adds no meaning for count, offset, book_id, or name_contains, and the sort explanation duplicates the schema text.

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 ('List') and enumerates the exact resources (shelves, books, chapters, pages), so it is immediately distinguishable from the create_*/update_*/delete siblings. It also names the related read tool ('get') it is not.

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 states two use cases ('see what exists', 'find recently updated pages') and routes the agent to an alternative ('To see what's inside a book, use get on the book instead'). Both when-to-use and when-to-use-something-else are covered.

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

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

Annotations already declare readOnlyHint=true, and the description earns credit for disclosing the return shape (matches with [type:id] refs, location, and text snippet), which the agent would otherwise not know since there is no output schema. It does not mention pagination behavior despite page/count parameters existing.

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?

Three sentences, zero filler: purpose first, then return shape, then the query grammar that is the genuinely non-obvious part. Nothing could be cut without losing information an agent needs.

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?

With no output schema, the description correctly explains what comes back, and it supplies the query syntax the thin schema omits. It falls short only on pagination semantics (the role of page/count) and on distinguishing itself from the 'list' sibling.

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 description coverage is only 25% — query has no schema description at all — so the description must carry that burden, and it does by spelling out the exact BookStack query grammar ("exact phrase", [tag=value], {in_name:word}, {updated_by:me}, {created_by:me}). The type enum is documented in the schema, but page and count are unexplained in both places.

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+resource (full-text search) and enumerates the entity types searched (shelves, books, chapters, pages), which is more precise than the bare name 'search'. It does not, however, differentiate itself from the sibling 'list', which likely also enumerates these entity types — an agent still has to infer which retrieves by keyword vs. paging.

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?

Usage is only implied: the presence of full-text syntax strongly suggests 'use this when you want keyword matching', but the description never says when to prefer it over the sibling 'list' or 'get', nor any exclusions. For a search tool sitting next to a list tool, an explicit routing sentence is the missing piece.

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

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

With no annotations, the description carries the full burden; it does disclose non-obvious behavior ('move a chapter (with its pages)'), which is useful. However, it omits mutation semantics such as whether omitted fields are left unchanged, whether tags replacement is destructive (that fact lives only in the schema), and any permission requirements.

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, front-loaded with the primary update operations and ending with the routing exclusion. Every clause carries information an agent needs; nothing is padded.

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 multi-entity mutation tool with no annotations and no output schema, the description covers the full operation set and the page-edit exclusion. It leaves some behavior implicit (side effects, error/precondition handling for mismatched type and id), but with the schema documenting per-type parameters the coverage is close to sufficient.

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 description coverage is 63%, so there are gaps; the description compensates by mapping capabilities to entity types, e.g. moving a chapter (move_to_book_id) and adding/removing books on a shelf (add_book_ids/remove_book_ids). It adds context beyond the schema's terse 'Shelves only'/'Chapters only' notes, though it does not define all 8 parameters.

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 names the specific verb+resource combinations: rename shelf/book/chapter, change description or tags, move a chapter, and add/remove books on a shelf. It also explicitly routes page edits away from this tool by naming update_page/edit_page, so an agent can separate it from siblings like create_book or delete without opening a schema.

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?

It gives a clear condition for the main alternative: 'For pages use update_page / edit_page.' That is an explicit when-to-use-else rule, but it does not clarify other boundaries (e.g. update vs create_*, or when removal should use delete instead of remove_book_ids).

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose a non-obvious trait — that WYSIWYG pages stay WYSIWYG and Markdown is converted to HTML — which is genuinely useful. However, it never warns that replace mode overwrites existing content, that tags are replaced wholesale, or what auth/permissions are needed for a mutation tool.

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 tight sentences: the capability list is front-loaded and the alternative/routing note follows. No filler or redundant restatement of the name.

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 7-parameter mutation tool with no annotations and no output schema, the description covers capabilities, the sibling alternative, and one important rendering behavior. It is nearly complete, though the destructive nature of replace mode and tag-replacement side effects are left to the schema.

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 description coverage is 86%, so the schema already documents id, mode, name, tags, markdown, and move targets. The description restates the mode options and adds the Markdown-to-HTML conversion note, but adds little semantic detail beyond the schema. Baseline 3 is appropriate.

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 (update) and resource (page) and then enumerates its capabilities: replace/append/prepend content, rename, retag, move. It explicitly distinguishes itself from the sibling edit_page, so an agent can route correctly without opening either schema.

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?

"For a small change inside an existing page prefer edit_page" gives a clear routing rule against the most confusable sibling. It stops short of stating explicit when-not conditions (e.g. bulk updates, new pages) or prerequisites, but the key alternative is named.

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