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

Beyond the annotations, the description adds meaningful behavioral context: the operation is additive and non-destructive to other memberships, and it requires a confirmation token because 'a group is what grants access.' This extra detail about the two-step token flow and security rationale is valuable and does not contradict any annotation.

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 with no filler: the first fronts the core action and differentiates it from update_user; the second explains the confirmation-token requirement. Every word 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?

The description, combined with the fully documented schema and output schema, covers everything an agent needs: the action, the alternative, the token flow, and the safety profile. Sibling tools like unassign_user_from_group further clarify its scope, and the description is complete for a single-assignment mutation tool.

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 the schema already documents all three parameters. The description adds semantic context for confirm_token by explaining why it is required and how it fits into the additive operation, but it doesn't need to repeat the schema definitions for user_id and group_id.

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 states a specific verb and resource: 'Adds one account to one group, leaving its other memberships alone.' It clearly distinguishes itself from update_user's groups list and from removal operations, so an agent can tell what the tool does at a glance.

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 explicitly frames the tool as 'the additive counterpart to update_user’s groups list,' telling the agent when to use this tool versus the alternative. The confirmation-token requirement is also called out as a prerequisite, giving clear operational context.

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?

Beyond the annotations, the description discloses the critical behavioral trait that conversion does not translate body content, with a concrete example: converting markdown to 'code' leaves markdown source as raw HTML text. This is exactly the kind of non-obvious behavior an agent needs to avoid false expectations. No contradiction with annotations.

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 three sentences, front-loaded with the core action, followed by the most important caveat and a direct usage directive. Every sentence earns its place with 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 the rich input schema, clear annotations, and presence of an output schema, the description is complete enough for an agent to call the tool correctly. It explains the key behavioral caveat, the intended use case, and the anti-use case, while the schema handles parameter details and the output schema handles return values.

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 schema description coverage is 100%, so the parameters are already well documented. The description itself does not add parameter-level meaning, but that is acceptable given the rich schema descriptions for path, editor, locale, page_id, and confirm_token. It receives the baseline score because the schema carries the load.

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 states a specific verb and resource: 'Changes the storage format of a page.' It further distinguishes the tool from generic page editing by clarifying that Wiki.js does not translate the body, making the purpose precise and differentiating it from update_page or other page mutations.

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 explicitly says when to use the tool: 'Use it to correct a page created with the wrong editor, not to reformat one.' This provides a clear when-to-use and when-not-to-use boundary without requiring the agent to infer usage from the schema.

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?

The description does not contradict the annotations and reinforces that a persistent folder is created. It adds a useful behavioral note that the slug appears in the URL of every file inside the folder, which goes beyond the raw annotation hints. However, it does not mention other side effects such as uniqueness requirements, permission needs, or the impact of parent_folder_id, so it remains only minimally transparent beyond annotations.

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 concise sentences with the primary action front-loaded and a single meaningful clarification about slug behavior. There is no redundant wording, repetition, or filler content.

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 simple create operation, the description, combined with a complete input schema, output schema, and annotations, is nearly sufficient. It clearly defines the core purpose and slug semantics. It lacks only explicit guidance about preconditions or edge cases such as whether parent folders must already exist, but most operational details are available through the structured fields.

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 100%, so the parameters are already well documented. The description adds some extra meaning to the slug by explaining its URL role for files inside the folder, but it does not substantively cover name or parent_folder_id beyond what the schema already provides. This meets the baseline without adding significant new parameter insight.

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 states a specific verb ('creates') and resource ('folder in the asset store'), making the tool's purpose immediately clear. It also distinguishes this tool from sibling tools like list_asset_folders, upload_asset, and delete_asset by targeting the creation action on asset folders.

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 intended usage is implied—creating a folder in the asset store—but there is no explicit guidance on when to choose this over alternatives, or any mention of preconditions like checking parent folders via list_asset_folders. It provides enough context for a straightforward create operation but omits exclusion or alternative tool 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?

It goes beyond the sparse annotations by disclosing a non-obvious behavioral trait: the comment is attributed to the API key's account, often a service account, and advises reflecting that in the text when relevant. This is exactly the kind of context that helps an agent avoid a subtle mistake.

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 with no filler: the main action is front-loaded, the optional reply behavior follows, and the attribution caveat earns its place. Nothing is redundant or verbose.

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 simple creation tool, a full input schema, and an output schema, the description is complete. It covers the key behavioral caveat (attribution) that the schema and annotations do not, while the schema documents required fields and output.

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 100%, so the baseline is 3. The description's 'optionally as a reply to another' largely paraphrases the reply_to schema field and adds little new parameter-level information beyond what the schema already provides.

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 clearly states the action ('Posts a comment'), the resource ('on a page'), and the optional reply mode, which distinguishes it from comment-list/update/delete siblings. The verb+resource pair is specific and 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 description gives clear context for use: post a new comment, optionally as a reply. It does not explicitly name alternatives like update_comment or delete_comment, but the creation semantics are obvious and no exclusion criteria are needed.

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?

Beyond the annotations (which only indicate write semantics, non-idempotence, and non-destructiveness), the description reveals the important behavioral trait that a new group has no permissions or page rules and therefore has no authorization effect until updated. This materially changes how an agent should reason about post-create actions.

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 concise sentences with the core action first and the key caveat second. No filler or redundancy.

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 single-parameter creation tool with an output schema and annotations covering the basic traits, the description covers all meaningful behavioral context: what is created, what it lacks, and what should be called next. No critical information appears to be missing for correct 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 description coverage is 100% and the only parameter, name, is already described as 'Group name.' The description adds no parameter-level meaning beyond what the schema provides, so the baseline of 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?

The description states a specific verb and resource ('Creates an empty group') and immediately clarifies what 'empty' means: no permissions and no page rules. This distinguishes it from update_group and other group lifecycle tools.

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 explicitly tells the agent that the created group grants nothing until update_group is called, effectively naming the follow-up alternative. This makes the basic create-then-update workflow clear.

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 mark this as a non-read-only, non-idempotent operation. The description adds useful behavioral context beyond those flags: duplicate creation returns PageDuplicateCreate, and the editor value determines how content is interpreted. This helps the agent predict failure modes and format requirements, though it does not cover all side effects.

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 convey the essential creation semantics, the duplicate-path failure mode, the alternative tool, and a critical editor/content relationship. There is no filler, and the most important operational constraint is front-loaded.

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?

Despite having 9 parameters, the schema is rich and an output schema exists, so the description need not repeat parameter documentation. It supplies the missing operational knowledge: path uniqueness per locale, routing to update_page, and editor/content coupling. An agent has enough context to invoke create_page correctly.

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 78%, so the schema does most of the work. The description adds meaningful value on top by explaining that the editor parameter controls content interpretation and that markdown source specifically requires editor="markdown", which is not obvious from the enum alone.

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 states a specific action and resource: 'Creates a page.' It explicitly differentiates from update_page by noting that existing paths trigger PageDuplicateCreate and require update_page, so an agent can distinguish this tool from its closest sibling 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?

The description gives explicit guidance: use this only when the path does not already exist in the locale, and use update_page for existing pages. It also clarifies that markdown content requires editor="markdown", which is a concrete selection criterion.

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 cover read/write and idempotency hints. The description adds useful behavioral consequences: sending an invitation email and the fact that a no-group account can log in but sees nothing. No contradiction with the annotations.

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 wasted words, and the main purpose is stated first. Each sentence adds operational value: authentication choice, group id sourcing, and groupless behavior.

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 an 8-parameter creation tool with an output schema, the description covers the key decision points and group behavior. It omits only the must_change_password semantics, which is a minor gap given the schema explains most other parameters.

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 description adds meaning for send_welcome_email (mail an invitation), password (local-account path), and groups (ids from list_groups, with visibility consequence). It does not clarify must_change_password, which the schema also leaves undescribed.

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?

"Creates an account" names the action and resource clearly. It is not a tautology, but it does not explicitly differentiate from sibling create_* tools; the title and resource name make that differentiation easy.

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 states the two local-account authentication paths (password vs send_welcome_email) and names list_groups as the source for group ids. It also explains the consequence of omitting groups, which tells an agent when groups are needed.

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?

Despite annotations already marking destructiveHint=true and readOnlyHint=false, the description adds concrete behavioral details: permanence, impact on embedding pages, and the confirmation-token requirement. This tells an agent what actually happens in the world, which exceeds the value of the annotations alone.

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, each carrying distinct information: the operation and its permanence, the consequence for pages, and the confirmation requirement. No filler, no restatement of the title, and the most important fact is front-loaded.

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 tool has a rich schema, output schema, and annotations, so the description need not explain return values. It covers the key behavioral and procedural facts. It loses one point because the two-step confirmation flow is stated only in the schema's parameter description, not in the tool description, creating a slight ambiguity for an agent reading the description alone.

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 100%, and both parameters have thorough descriptions in the schema (source of asset_id, two-step confirm_token behavior). The tool description repeats only that a confirmation token is required, without adding new parameter-level meaning beyond what the schema already provides.

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 starts with a clear, specific action: 'Deletes an asset permanently.' The qualifier 'permanently' distinguishes it from any move/rename or soft-delete behavior, and the resource 'asset' cleanly separates it from sibling page, comment, user, and group tools. It needs no comparison to be understood.

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 gives clear context for using the tool: it is destructive, has permanent consequences (broken images/dead links), and requires a confirmation token. It does not explicitly state when-not-to-use or name alternatives, but no alternative delete-asset tool exists among siblings. Minor gap: it says 'Requires a confirmation token' without clarifying that the token may be omitted on the first call to receive one, though the schema covers this.

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 mark the operation as destructive and idempotent. The description adds valuable behavioral context beyond the annotations: replies are not cascade-deleted, and a confirmation token is needed, implying a non-final first call. Nothing contradicts the provided annotations.

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 short, purposeful sentences lead with the core action, then state the important exception about replies, then the confirmation requirement. There is no filler or redundancy.

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 covers the essential behavioral facets: permanence, non-cascade of replies, and the confirmation-token prerequisite. Combined with strong annotations and a present output schema, an agent has everything needed to invoke this tool correctly.

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 100%, so both comment_id and confirm_token are already well documented. The description reinforces the confirmation-token flow but does not add meaning beyond what the schema already provides, so the baseline score of 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?

The description uses a specific verb ('Removes'), a clear resource ('a comment'), and a defining qualifier ('permanently'). This cleanly distinguishes the tool from siblings like update_comment, get_comment, and list_comments without requiring schema inspection.

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 gives clear operative guidance: deletion is permanent, replies are preserved, and a confirmation token is required. It doesn't explicitly name alternatives or state when not to use the tool, but the deletion intent and the two-step confirmation requirement provide enough context for correct selection.

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 destructiveHint=true, and the description adds meaningful context beyond that: members are not deleted, they lose only group-derived access, and the operation requires a confirmation token. This discloses important behavioral and safety-relevant traits not inferable from the annotations alone.

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 short sentences with the core action front-loaded. The first sentence states what is removed, the second covers the two most important consequences and prerequisites. There is no redundant or filler content.

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 destructive two-step operation, the description covers the essential non-obvious facts: account preservation, access loss, and confirmation token requirement. Combined with a complete schema and output schema, this is sufficient for an agent to call the tool correctly, though it does not discuss failure conditions or group membership edge cases.

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 100%, so the schema already documents group_id and confirm_token, including the token pattern and the omit-to-receive-one behavior. The description adds only a high-level requirement for a confirmation token and does not provide additional semantic detail beyond the schema.

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 the specific verb-resource pair 'Removes a group' and immediately distinguishes the impact from user deletion by stating members keep their accounts. This is clear and differentiates delete_group from siblings like delete_user and delete_page.

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 when to use the tool through the consequence 'members keep their accounts but lose whatever access the group gave them,' which helps an agent decide if group deletion is appropriate. However, it does not explicitly name alternatives such as unassign_user_from_group or update_group, so the routing guidance is only implied, not 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?

Annotations already declare destructiveHint=true, but the description adds meaningful detail beyond that: the page's history is also deleted, Wiki.js has no trash, the action cannot be undone, and a confirmation token is required. This materially raises the agent's awareness of consequences.

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 efficient sentences deliver the core purpose, destructive scope, irreversibility, and the confirmation requirement. There is no filler or repetition of schema details.

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 a fully described schema, an output schema, and annotations covering safety profile, the description fills the remaining critical gaps: history deletion, no-trash irreversibility, and the confirmation-token workflow. Nothing essential is missing for an agent to invoke this correctly.

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 input schema already documents all parameters with 100% coverage, including path format, locale behavior, and the confirm_token lifecycle. The description adds only a general statement about requiring a confirmation token, which mirrors schema information rather than substantially enhancing it.

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 uses a specific verb and resource ('Deletes a page and its history') and clearly distinguishes this from related tools like purge_page_history by scoping the operation to the page itself. It also signals irreversibility, which sharpens the purpose.

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 gives clear behavioral context: irreversible deletion with no trash and a required confirmation token. It does not explicitly name alternatives or when-not-to-use conditions, but the context is strong enough for an agent to recognize this is the final deletion tool for a page.

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 flag destructive and non-read-only behavior, but the description adds meaningful detail about what exactly gets destroyed: the tag itself and its association with every page, while confirming pages are untouched. The confirmation-token requirement is also a valuable behavioral disclosure beyond the basic mutation hints.

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 with no wasted words. It front-loads the primary action and scope, then adds the critical safety clarification and the confirmation requirement.

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 covers the destructive effect, the safety guarantee about pages, and the confirmation mechanism. With an output schema present and the input schema fully documenting parameters, nothing essential for calling this tool correctly is missing.

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 100%, with tag_id and confirm_token both fully documented in the input schema. The description adds little parameter-level meaning beyond saying a confirmation token is required, and the schema itself already explains the two-step token flow. Baseline 3 is appropriate since 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?

The description states a specific action ('removes a tag') with a precise resource and scope ('from the wiki and from every page that carries it'), and it explicitly clarifies what is not affected ('the pages themselves are untouched'). This clearly distinguishes delete_tag from update_tag and delete_page.

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 when to use the tool: when a tag should be removed wiki-wide without deleting pages. It also notes the confirmation-token requirement, which is useful procedural context. However, it does not explicitly name alternatives or state when not to use this tool, leaving routing between siblings 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?

Annotations already flag this as destructive and non-read-only. The description adds the meaningful consequence that the deleted user's authored pages must be transferred to another account, and that confirmation is part of the flow. It does not spell out irreversibility, but destructiveHint covers the core safety signal.

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 short sentences deliver the action, the critical ownership-transfer constraint, and the confirmation requirement with no filler. The most important behavioral information is front-loaded.

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?

Between the description, full parameter schema, output schema, and annotations, an agent has almost everything needed to invoke deletion correctly. The only minor gap is that the two-step confirmation flow (omit confirm_token first, receive token, then confirm) is left to the schema rather than stated explicitly.

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?

With 100% schema description coverage, every parameter is already documented. The description restates the replace_with_user_id requirement and the confirmation-token need without adding much parameter-level detail beyond the schema, so it meets the baseline but does not elevate it.

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 'Removes an account,' a specific verb-object pair that clearly identifies this as a permanent user-deletion tool. The added detail about page inheritance distinguishes it from non-destructive user-state tools like set_user_active without 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?

The description states the key precondition ('replace_with_user_id is required') and the confirmation-token requirement, giving an agent clear context for when deletion can proceed. It does not explicitly call out when to prefer set_user_active over delete_user, so it stops short of full alternatives 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?

Annotations already convey the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description adds modest behavioral context by explaining the semantics of omitting to_version. However, that omission behavior is also described in the to_version parameter schema, and the unified diff format is likely covered by the output schema. No new behavioral traits such as rate limits, auth requirements, or side effects are disclosed, so the description adds only limited value beyond the structured fields.

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 only two sentences long, front-loaded with the core action and resource, and includes the key alternative mode and value proposition without any filler. Every phrase 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 read-only diff tool, the description—together with full schema parameter documentation, rich annotations, and an output schema—provides everything an agent needs to select and call it correctly. The one-call advantage and optional live comparison are sufficient for context. No critical selection or invocation detail is missing.

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 100%, and each parameter is already well-documented: page_id as a numeric Wiki.js id, to_version with its omission behavior, from_version as the older version from list_page_history, and context_lines with a default. The tool description does not and need not repeat this information, so the baseline score of 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 action: 'Returns a unified diff between two versions of a page,' and clearly distinguishes its purpose from sibling tools like get_page_version by focusing on a diff rather than a full page body. The optional live-page comparison mode is also clearly described. An agent can understand exactly what this tool does 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?

The description gives clear usage context: it answers 'what changed here' and does so 'in one call instead of two full page bodies,' which tells the agent when this tool is preferable to fetching multiple versions. It stops short of explicitly naming alternatives like get_page_version or stating when not to use it, so it earns a 4 rather than a 5.

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?

The description adds meaningful behavioral context beyond the annotations. It explicitly reassures that 'Nothing is lost,' clarifies the global scope across the entire wiki, and discloses the performance cost of re-rendering every page. It is consistent with the idempotentHint and destructiveHint=false annotations, and the readOnlyHint=false is respected since this is a mutation of the cache.

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 a single tightly written sentence that leads with the action, then immediately provides the two most important consequences: nothing is lost, and performance temporarily degrades on busy instances. There is no filler or redundant restatement of the title.

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 zero-parameter, idempotent cache-flush operation with annotations covering safety and an output schema available, the description is complete enough. The only minor gap is the lack of explicit guidance about when flushing is appropriate versus alternatives, but the behavioral and performance context covers what an agent needs to make a safe call.

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 tool has zero parameters, so there is no parameter semantics burden on the description. The baseline for a zero-parameter tool is 4, and the description correctly states the global scope ('whole wiki') rather than implying any configurable target.

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 a specific verb and resource: 'Drops Wiki.js’ rendered-page cache for the whole wiki.' This clearly distinguishes it from sibling cache-related rebuild tools like rebuild_page_tree and rebuild_search_index by specifying exactly what is flushed. The scope ('whole wiki') removes ambiguity about whether the action is targeted.

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 when to use the tool by explaining the consequence: every page must be rendered again on first access, with a temporary performance impact on a busy instance. However, it does not explicitly state when to choose this tool over alternatives, nor does it provide exclusions or conditions such as 'use when cached pages are stale.'

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 idempotentHint=true, so the safety profile is covered. The description adds context about the returned fields ('source and rendered HTML'), which is useful beyond the annotations. No behavioral contradictions are present.

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 a single, clear sentence that front-loads the verb and resource. Every word contributes meaning, with no filler or redundancy.

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 one required parameter, a fully described schema, rich annotations, and an available output schema, the description supplies enough context for an agent to select and invoke the tool correctly. Nothing critical is missing.

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 schema fully documents comment_id as a 'Numeric Wiki.js id' with min/max constraints, so the high coverage baseline applies. The description's 'by id' phrasing only restates what the schema already communicates without adding new meaning.

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 uses a specific verb ('Returns'), identifies the resource ('a single comment'), and specifies the lookup key ('by id'). It also adds useful return content details ('source and rendered HTML'), clearly distinguishing it from list_comments and comment mutation tools.

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 use case is implied: this tool is for fetching one comment when you have its comment_id. However, it does not explicitly state when to prefer this over list_comments or mention any alternatives or exclusions.

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, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context by specifying what the returned group includes and why it matters for update_group, going beyond the annotations without contradicting them.

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, no filler. The first sentence front-loads the primary return value, and the second justifies when to call it while explaining a non-obvious coupling to update_group. Every word 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?

This is a simple read tool with one well-documented parameter, rich annotations, and an output schema. The description fully orients an agent: what it returns, why it is authoritative, and how it relates to a mutating sibling. Nothing essential is missing.

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 input schema fully documents group_id with a clear description ('Numeric Wiki.js id') and constraints. The tool description adds no parameter-specific meaning, but since schema coverage is 100%, the baseline of 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?

The description uses a specific verb and resource: 'Returns one group with its global permissions, its page rules and its members.' It also clarifies the tool's unique role as the authoritative source for access-control questions, distinguishing it from list-oriented siblings like list_groups.

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 explicitly states a key use case: this is the starting point for update_group, because that mutation replaces the whole rule set. It does not enumerate when not to use it relative to list_groups, but the given usage context is strong and actionable.

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 and idempotentHint, so the safety profile is covered. The description adds useful behavioral context about the data source ('curated by hand') and the locale scoping, going beyond the annotations.

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 convey the core purpose, the scope, and the key distinction from a sibling tool. Every word earns its place, and the most important information is front-loaded.

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 no-parameter read-only tool with an output schema and strong annotations, the description is fully sufficient. It clarifies the data source and the relationship to get_page_tree, leaving no critical gaps for correct 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?

The tool has zero parameters, and the schema coverage is 100%, so there are no parameter gaps. The description adds the relevant 'per locale' semantic without needing to document any input fields.

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 states a specific resource ('sidebar navigation as configured') and a clear scope ('per locale'), and explicitly differentiates it from get_page_tree. This distinguishes it from its closest sibling without needing to open any schemas.

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 explicitly tells the agent when to use this tool vs. the alternative: it is hand-curated navigation, not the actual page tree, and get_page_tree reflects real pages. This gives clear selection criteria.

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 mark it read-only, idempotent, and non-destructive; the description adds real behavioral detail on top: mode-specific output, truncation to the result budget, the 'cheapest' outline mode, and refusing ambiguous sections rather than guessing. No contradiction with annotations.

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, front-loaded with the primary action, and every sentence earns its place. The mode list and content-windowing guidance are dense but neither padded nor redundant with the schema.

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 read-only fetch tool with 7 parameters and an output schema, the description covers addressing, mode selection, large-page handling, and truncation. The only mild omission is an explicit 'must provide page_id or path' requirement, but the opening sentence makes that implied strongly enough.

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 description adds beyond the schema by tying section/offset/max_chars specifically to mode=content, explaining windowed reading, and clarifying the identity role of path+locale. This materially helps an agent pick and combine 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?

Description opens with 'Reads one page, addressed by page_id or by path plus locale', giving a specific verb, resource, and addressing modes. It distinguishes itself from sibling list/search tools by targeting a single page and enumerates four distinct output modes.

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?

Provides explicit mode-selection guidance: 'outline' as cheapest way to inspect long pages, and content-mode windows for large pages to avoid truncation. It doesn't name sibling alternatives (e.g., render_page) or state when not to use this tool, so it doesn't reach fully explicit exclusion 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructiveness, so the description's job is lighter. It adds useful context: the returned version is newer than the one read, includes author and timestamp, and is meant to be redone on top rather than discarded.

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 tight sentences with no filler. It front-loads the core behavior and then explains the practical value, with every clause earning 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 single-parameter read-only tool with full schema coverage and an output schema, the description is complete. It explains why this tool exists, what it returns, and how the result should be used in the conflict-resolution workflow.

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 schema documentation covers the single page_id parameter fully with 'Numeric Wiki.js id.' The description does not need to add parameter details, and at 100% coverage the baseline of 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?

The description states a specific verb, resource, and distinguishing context: it returns the newer version of a page that update_page points at when refusing a write. This clearly separates it from generic page/version retrieval tools like get_page or get_page_version.

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 gives clear context by naming update_page and the conflict scenario it serves. It does not explicitly list when not to use it or name an alternative, but the conflict-resolution trigger is specific enough to guide selection.

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 mark this as read-only and idempotent. The description adds useful behavioral detail beyond annotations, especially the truncation caveat for very wide levels due to Wiki.js's unlimited query. It also clarifies that only direct children are returned, which is not evident from annotations.

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 concise sentences with no filler. The core purpose is front-loaded, mode details follow, and the truncation caveat is placed last. Every sentence earns its place without being verbose.

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 read-only tree-browsing tool, the description covers purpose, scope, mode filtering, and a behavior caveat. The presence of an output schema reduces the need to document return values. Minor gaps are the lack of an explicit default mode and the absence of named sibling alternatives for recursive traversal.

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 most parameters. The description adds a small amount of value by spelling out the mode values, but it mostly repeats what the enum conveys. It does not add new meaning for include_ancestors or locale beyond the schema.

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 a specific verb and resource: it lists pages and folders directly under a path. It also differentiates this structural view from search, making it easy to distinguish from search_pages and list_pages. The mode behavior further clarifies exactly what is returned.

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 states clearly that this is a structural wiki view, suggesting when it should be used over search. It implies its scope as direct children under a path, though it does not explicitly name alternative tools for recursive or filtered listings. Overall, the usage context is clear but exclusions are not spelled out.

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 signal readOnly, idempotent, and non-destructive behavior. The description adds useful context that the returned content includes the page's full body as it existed in that version, which clarifies what the agent receives beyond the schema.

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 concise sentences deliver the core purpose and the main alternative usage in a front-loaded manner. There is no fluff or redundant restating of the tool 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?

With a valid output schema present, full parameter documentation, and annotations covering safety, the description is complete enough for correct invocation. It also covers the key decision point about using diff_page_versions for comparisons.

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 100%, so the schema fully documents both page_id and version_id. The description adds no new parameter-level detail, which is acceptable given the schema's completeness.

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 clearly states the tool's function: return a single historical version of a page with its full body. It explicitly distinguishes it from diff_page_versions by noting that the latter is cheaper for comparing changes.

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 explicit guidance on when to use this tool versus an alternative: use it to retrieve one version, and use diff_page_versions when interested in changes. This gives an agent a clear decision rule.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds value beyond annotations by disclosing that host filesystem and database-host fields are 'deliberately not requested,' setting expectations about the response scope, and framing the call as proof that the URL and API key work. No contradiction with annotations exists.

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, each earning its place: the content summary is front-loaded first, followed by the when-to-use diagnostic guidance, then the deliberate field-exclusion caveat. There is no filler and no repetition of what the schema or annotations already state.

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 zero parameters, full annotation coverage of the read-only/idempotent safety profile, and an output schema present, the only remaining job for the description is scope and usage — both are covered, including a caveat about deliberately omitted host-level fields. Nothing an agent needs to correctly select and invoke this tool is missing.

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 tool takes zero parameters, so the rubric's baseline of 4 applies; there are no parameter semantics to clarify. The description instead enumerates the response contents (version, database, host summary, counts), which is more useful for this no-argument tool than parameter prose would be.

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 enumerates exactly what is returned — version, database, host summary, site title/description, and totals for pages, users, groups, and tags — going well beyond the terse title. This site-level resource is clearly distinct from all 60+ sibling tools, which target pages, users, tags, assets, comments, and other specific resources. An agent can identify what this tool provides 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?

The description gives an explicit scenario: 'The first call to make when something is not behaving — it proves the URL and the API key work at all.' This tells the agent when to invoke it as a diagnostic smoke test. It does not name when-not-to-use cases or alternatives, though none of the siblings genuinely compete with a site-info call, so this is a minor gap.

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 cover read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context by stating that credential data is never returned and by naming specific included fields (group memberships, TFA status). This goes beyond the annotations.

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 concise sentences with no filler. The core purpose is front-loaded, followed by key detail and a relevant negative guarantee. Every part 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 simple single-parameter read tool with a full input schema, an output schema, and comprehensive annotations, the description is complete. It explains what is returned, what is not returned, and identifies the required ID.

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 100% for the single user_id parameter, which is already documented as a numeric Wiki.js id. The description references 'one account' but does not add parameter format or usage details beyond what the schema provides, 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?

The description uses a specific verb and resource ('Full detail for one account') and clearly identifies the object returned, including group memberships and TFA status. This distinguishes it from list_users or search_users, which would return multiple or filtered users.

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 usage when a caller needs complete detail for a single specific user, but it does not explicitly contrast with sibling tools like list_users or search_users, nor state when not to use it. The guidance is adequate but implicit.

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?

The annotations already declare this as a read-only, idempotent, non-destructive operation, and the description goes well beyond them. It discloses the expensive per-request-per-page behavior, explains that matching happens locally after fetching, and specifies the return granularity as matching lines with context rather than full pages. This is substantive 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?

The description is four sentences with no wasted words. It leads with the core purpose, then explains why the tool exists, then gives cost and filtering guidance, and finally states the return format. 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?

For a tool with seven parameters, an output schema, and strong annotations, the description covers all the essential contextual needs: purpose, cost model, filtering strategy, and output format. An agent can correctly select and invoke this tool without needing additional information.

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 high at 86%, so the schema already documents most parameters. The description adds valuable semantics by explaining that path_prefix, tags, and locale are used to narrow the expensive search, and that max_pages directly controls cost. This goes 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?

The description starts with a specific verb and resource: it searches the actual text of pages using a regular expression. It clearly distinguishes itself from sibling search tools by explaining that Wiki.js's default search engine does not index page content, so this tool fills that gap.

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 gives clear context for when to use the tool: when you need to search page content, because the default search engine doesn't index it. It also provides explicit operational guidance to narrow with path_prefix, tags, or locale and keep max_pages small. It doesn't explicitly name an alternative sibling or state when not to use it, but the context is strong enough.

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 mark the call as read-only, idempotent, and non-destructive, and the description adds meaningful safety context: Wiki.js stores only a truncated key and never returns the secret, so nothing in the result can authenticate. This is valuable behavioral disclosure beyond the structured annotations.

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 action and result fields, followed by a concise security caveat. There is no filler or repetition of schema or annotation 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 zero-parameter list operation with annotations and an output schema already present, the description covers everything else an agent needs: what is listed, included status fields, and the credential-safety caveat. No missing behavioral or usage detail remains.

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 schema has zero properties, so there are no parameter semantics for the description to explain. The description appropriately focuses on what the response covers rather than inputs, earning the baseline for a no-parameter tool.

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 the specific verb 'Lists' and the resource 'the wiki's API keys', then enumerates the exact fields returned: expiry, revoked status, and whether API access is on. This clearly distinguishes the tool from mutating siblings like revoke_api_key and set_api_state.

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 read-only listing purpose and the mention of API-access state provide clear context for when an agent should call this tool. It does not explicitly name alternatives, but among siblings only revoke_api_key and set_api_state mutate API-key state, making the intended use evident.

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 establish read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond annotations: Wiki.js returns one level at a time, and Folder 0 is the root. This helps the agent understand traversal semantics without overexplaining.

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 with no filler. The primary action is front-loaded, and the one-level-per-call behavior is stated immediately after, making this easy to parse.

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 a single simple parameter, strong annotations, and an output schema already present, the description covers everything an agent needs to invoke the tool correctly. The key behavioral nuance (one level per call) is explicitly included.

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%: the parent_folder_id parameter is fully described with type, range, and root default. The description reinforces that Folder 0 is the root but adds no new parameter semantics beyond what the schema already provides.

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 states a specific action ('Lists the folders directly under an asset folder'), identifies the resource type (asset folders), and scopes the result to one level. It also clarifies the special root folder (Folder 0), distinguishing this from listing assets or pages.

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 clearly implies when to use this tool: when you need the immediate children of an asset folder. It also gives behavioral guidance that a deep tree requires one call per level, helping the agent plan multi-step traversal. It does not explicitly name alternatives or exclusions, but none are necessary given the unique sibling context.

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, idempotentHint=true, and destructiveHint=false. The description goes beyond annotations by disclosing that assets are flat within a folder and that Wiki.js lacks search across assets—both useful behavioral constraints. It does not describe pagination or result ordering, but the output schema fills some of that gap.

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 three sentences long and front-loads the core purpose. Each sentence contributes distinct information: what is listed, root meaning, and the flat/no-search behavior that justifies traversal. Slightly verbose with 'so finding one means walking list_asset_folders,' but still efficient.

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 the tool's simplicity, the presence of an output schema, and strong annotations, the description covers everything an agent needs: the resource type, folder scope, root behavior, flat layout, and the traversal requirement due to lack of search. No critical usage detail is missing.

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 100%: both parameters are described in the schema, including folder_id's root default and kind's filtering purpose. The description largely restates the folder 0 root concept and adds traversal context, but it does not meaningfully extend the parameter-level detail already present in the schema.

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 states a specific verb and resource: 'Lists the images and files in one asset folder.' It also clarifies scope with 'one asset folder' and 'Folder 0 is the root,' which distinguishes it from folder-level operations like list_asset_folders and mutation tools like upload_asset.

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 operational context: assets are flat within a folder and Wiki.js has no cross-asset search, so finding an asset requires walking list_asset_folders. This effectively tells an agent when and how to use the tool, though it does not explicitly name alternative tools or state when not to use it.

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 establish the read-only, idempotent, non-destructive profile, so the description's job is lighter. It adds valuable behavioral caveats: the page is addressed by path rather than id and an empty list is ambiguous, which is a meaningful interpretive warning not present in annotations.

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 carry all the important information: the action, the addressing mode, the exception, and the ambiguity caveat. The main point is front-loaded and every clause contributes.

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 annotations covering safety semantics, the schema covering all parameters, and an output schema present, the description covers the remaining contextual gaps: how to address the page and how to interpret an empty result. Nothing needed to invoke the tool correctly is missing.

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 100%, with detailed explanations for path (no leading slash/locale prefix, examples) and locale (default, identity). The description only restates 'path and locale' without adding parameter-level detail, so it stays at the baseline for fully covered schemas.

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 a specific verb and resource: 'Returns the comments on one page,' and immediately states the addressing mode (path and locale). It also distinguishes itself from id-based siblings by noting this is 'not by page id,' so an agent can separate it from get_comment and page-id tools.

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 clearly says to address the page by path and locale rather than page id, which is a direct usage constraint. It also points to get_site_info as the sibling to use when an empty result may mean comments are disabled, though it does not spell out when to use get_comment or other comment tools.

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 mark this as read-only, idempotent, and non-destructive. The description adds useful context beyond that: it explains that the result includes user counts and that isSystem groups (Administrators and Guests) are permanent and should not be deleted. This helps the agent interpret results and avoid future destructive actions.

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, purposeful sentences. The first states exactly what the tool does, and the second conveys an important caveat about system groups. There is no fluff or repetition of schema 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 simple, read-only list tool with no required parameters and an output schema, the description is largely complete. It names the resource and result content, and highlights the important isSystem caveat. The only notable gap is the lack of guidance on how 'filter' behaves, though the tool can be safely invoked with no arguments.

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 compensate for the undocumented 'filter' and 'order_by' parameters. It does not mention either parameter, leaving 'filter' ambiguous and forcing the agent to guess its behavior. The enum on 'order_by' provides some self-documentation, but the description adds nothing.

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 starts with a specific verb ('Lists') and resource ('the wiki's groups') and adds the key detail that it includes user counts. This clearly distinguishes it from siblings like get_group, list_users, or search_groups.

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 makes the basic listing use obvious and even warns that system groups should not be deleted, but it does not explicitly say when to prefer this tool over alternatives like get_group or search_users. Usage context is implied rather than stated.

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 mark this as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: locale is part of page identity and all page tools fall back to WIKIJS_LOCALE, warning that a misconfigured locale will cause pages not to be found. This helps the agent understand operational impact.

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: the first states the core purpose directly, and the second provides a brief, high-value rationale. No filler or redundant restatement of the title or schema.

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 simple read-only listing tool with one optional parameter, an output schema, and strong annotation coverage, the description fully supports correct invocation. It also explains real-world consequences around locale configuration, making it complete for an agent.

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% for the single parameter, and the schema description for installed_only already explains the default and why it matters. The tool description adds little parameter-specific meaning, but it does not need to because the schema carries the load.

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 clearly states that the tool reports which locales are installed and which one is the default, naming a specific resource and outcome. It distinguishes itself from the sibling tools, none of which cover locale listing.

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 gives explicit context: 'Worth checking once per wiki' and explains why the locale matters for page tools via WIKIJS_LOCALE fallback. It lacks explicit when-not-to-use instructions, but no obvious alternative locale tool exists among the siblings, so the guidance is clear enough.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavior beyond annotations: results are ordered newest first, include who changed what and when, and the query paginates. This gives an agent useful expectations about response shape and iteration.

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 concise sentences with no filler. The first sentence states the core behavior and ordering, the second highlights pagination, and the third connects the output to related tools. Every sentence adds information an agent needs for correct invocation and follow-up.

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 tool has five optional parameters, a complete schema, and an output schema, so the description does not need to explain return values. It sufficiently covers pagination, ordering, and downstream usage, leaving no significant gap for an agent to select or call the tool correctly.

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 100%, so the parameters are already fully documented in the input schema. The description does not add parameter-level detail, but it correctly signals that page identity is tied to path/locale and page_id. Since the schema carries the burden, a 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?

The description uses a specific verb and resource: it 'Lists the stored versions of a page, newest first, with who changed what and when.' It clearly distinguishes list_page_history from page-listing siblings like list_pages and get_page, and even ties the output to downstream version tools, so an agent knows exactly what this tool is for.

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 gives clear context: use this when you need a page's stored versions and version ids. It explicitly notes that the returned version ids are what get_page_version, diff_page_versions, and restore_page_version consume, which guides downstream selection. It does not explicitly state when not to use it, but the intended role is clear enough.

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?

The annotations already mark this as a safe, idempotent read operation. The description adds important unannotated behavioral traits: the entire link graph is returned in a single unfiltered request, and on large wikis the output is truncated. This is valuable context for an agent to anticipate incomplete results.

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 every one earns its place: core behavior, practical use case, and a crucial caveat about truncation. The most important information is front-loaded, and there is no filler or redundant content.

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 simple read-only tool with one optional parameter, an output schema, and safety annotations, the description covers what it returns, the locale scope, why to use it, and its truncation limitation. Nothing essential is missing for an agent to decide whether and how to invoke it.

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 100%; the locale parameter is fully documented in the schema, including its default and role in page identity. The description reinforces that the graph is scoped to one locale, but it does not add new parameter-level details beyond what the schema already provides, so a 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?

The description names a specific verb and resource: returns every page with its internal links, the wiki's link graph for one locale. It clearly distinguishes itself from sibling tools like list_pages by focusing on internal links rather than just pages.

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 explicitly identifies when to use the tool: 'finding what would break before moving or deleting a page.' It also warns that Wiki.js returns the whole graph at once with no filter and may be truncated on large wikis, which implies a limitation, though it does not name alternative tools or provide explicit when-not-to-use 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?

Annotations already indicate read-only and idempotent. The description adds behavior beyond annotations: default ordering, matched-vs-shown counts so short answers aren't mistaken for small wikis, no available offset, and exclusion of page content. No contradiction with annotations.

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, each earning its place: purpose, a self-describing output subtlety, and a filter/alternative pointer. No fluff or restatement.

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 the output schema exists and annotations cover safety, the description covers all key usage aspects: what's returned, default ordering, paging limitation, filtering strategy, and pointer to get_page. Nothing critical for a correct call is missing.

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 high (86%) and includes descriptions for most parameters. The description adds the default ordering behavior ('newest first') and reinforces that limit should not be used as a paging mechanism, which clarifies direction/limit semantics. It doesn't add detail beyond schema but provides useful strategic context.

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: 'Lists pages with their metadata' and defaults to newest first. It clearly distinguishes from get_page by explicitly saying it returns no page content, and clarifies it's a list rather than a search.

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 guides to filter by tags/locale/creator_id/author_id instead of paging because Wiki.js lacks an offset, and points to get_page when page content is needed. It doesn't name search_pages or grep_pages as alternatives, leaving some ambiguity among list-vs-search siblings.

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 the operation read-only and idempotent, so the description does not need to restate that. It adds meaningful behavioral context by explaining that the default 'Database - Basic' engine only indexes titles and descriptions, which is not obvious from the tool name or annotations.

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 with no filler: the first states what the tool reveals, and the second adds a targeted, useful caveat. It is front-loaded and 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 parameterless, annotated, read-only tool with an output schema, the description covers what an agent needs to know: what the result represents and why it matters. No important context is missing for correct invocation or interpretation.

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 tool has zero parameters, so the input schema is fully covered and there is nothing for the description to document. The baseline of 4 applies because no parameter explanation is needed.

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 title and description together clearly identify the tool as listing the wiki's configured search engines. The description goes beyond a generic statement by explaining the operational relevance, and distinguishes this from the related search_pages tool by linking the engine type to search behavior.

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 explicitly advises checking this tool before trusting search_pages, giving a concrete when-to-use context. It also explains the practical consequence of the default engine, which helps an agent decide whether to call this tool first or interpret search results cautiously.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a meaningful behavioral detail beyond annotations: credentials in the configuration are redacted. This helps the agent set expectations about the data returned.

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 with no filler. The first sentence front-loads the resource and output fields, and the second adds a valuable warning about credential redaction. Every word 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 zero-parameter, read-only listing tool with a rich output schema and full annotations, the description is complete. It names the resource domain, gives examples of backend types, lists the displayed status fields, and discloses redaction. Nothing needed for correct invocation is missing.

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 tool has zero parameters and 100% schema coverage, so there are no parameter semantics to document. Per the baseline for 0-param tools, a score of 4 is appropriate; the description adds useful context about what is listed even though it does not discuss 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 states a specific verb ('list') and resource ('configured storage backends') with concrete examples (git mirrors, S3 buckets, local file dumps), plus the key returned attributes (sync status, last error). This clearly distinguishes it from other list_* siblings, none of which concern storage backends.

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 this tool is for inspecting configured storage backends and their health, but it does not explicitly state when to use it, when not to use it, or name alternatives. Since no sibling targets storage, usage is fairly obvious, but explicit guidance is absent.

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, idempotentHint, and destructiveHint, so the safety profile is fully covered. The description adds value beyond annotations by explaining the tool returns every tag and includes last-used timing, plus the conceptual behavior of tags as a cross-cutting index. No contradictions with annotations.

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 with no wasted words. The first sentence front-loads the core function and return content, and the second adds actionable guidance about how to use the result. 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?

For a zero-parameter, read-only listing tool with an output schema, this description is complete. It covers what is returned, why tags are valuable, and what to do next with a result. No missing information is needed for correct invocation or selection.

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 tool has zero parameters and schema description coverage is 100%, so there is nothing for the description to add about parameter meaning. The baseline of 4 applies because parameter semantics are a non-issue here.

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 states a specific verb and resource: it lists every tag in the wiki and specifies the returned fields (display title and last-used time). It also clearly differentiates itself from search by positioning tags as a cross-cutting index, so an agent can distinguish it from search_tags 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?

The description gives clear usage context: tags are a good starting point and can be fed into list_pages. It references search as a less ideal alternative, but it does not explicitly name search_tags or provide exclusion criteria, so it falls just short of fully explicit when-to-use versus when-not-to-use 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable behavioral context: providerKey semantics and the fact that email addresses are returned because they serve as the login. It does not mention pagination details, but the limit parameter in the schema partially covers that.

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 short sentences, front-loaded with the primary action and followed by two high-value clarifications about providerKey and email. Every sentence earns its place with no wasted wording.

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 an output schema and read-only annotations present, the core behavior is adequately described. The main gaps are the absence of guidance on when to prefer search_users over list_users and a slightly mismatched limit rationale, which keep it from a perfect score.

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 main description adds no parameter-specific meaning, but the schema documents limit and filter, and order_by's enum values are self-explanatory. However, the limit description contains an irrelevant 'page lists / tags / locale / path' rationale that appears copied from a different tool and mildly muddies user-list semantics.

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 the specific verb+resource 'Lists the wiki's user accounts', which unambiguously identifies the operation and target. It also clarifies the returned login-related fields (providerKey, email), making the purpose concrete and distinct from user creation or mutation tools.

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 gives no explicit guidance on when to use list_users versus search_users or get_user. While 'Lists' implies a general listing operation and the filter parameter hints at narrowing, no conditions, exclusions, or alternatives are stated.

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?

Beyond the annotations' destructiveHint and idempotentHint, the description warns that every page path changes and every external link breaks, and notes that a confirmation token is required. This exposes the real-world blast radius and safety mechanism without contradicting the annotations.

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: action first, rationale second, impact and safety requirement third. No filler or repetition of schema property names.

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 destructive bulk operation, the combination of the description and schema covers purpose, trigger, blast radius, confirmation flow, and locality of the parameters; the existing output schema handles return-value documentation. No critical context is missing.

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?

Since schema description coverage is 100%, the baseline is 3. The description restates source/target direction and mentions confirmation, but it adds no parameter detail beyond what the schema's field descriptions already provide.

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 a specific verb ('Moves'), an explicit resource ('all pages'), and the scope ('from one locale to another, across the whole wiki'). This clearly separates it from the sibling move_page tool, which handles single pages.

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 concrete trigger condition ('The usual reason is a wiki set up under the wrong locale code'), which tells the agent when this bulk migration is appropriate. It does not explicitly name the single-page alternative or list when-not conditions, so it stops short of full routing 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?

The description discloses a key behavioral trait beyond the annotations: internal links are not rewritten, a side effect an agent must know before invoking. Since readOnlyHint, destructiveHint, and idempotentHint already cover the safety profile, the added link-rewriting caveat is genuine value. It does not mention the two-phase confirm-token flow, though that is documented in the confirm_token parameter description.

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 with zero filler: the action is front-loaded in sentence one, and the critical caveat follows immediately in sentence two. Every clause earns its place, and the warning is positioned where the agent will see it before acting.

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 covers the core action and the most important caveat, and the output schema plus 100% param coverage carry the rest. However, there is a real gap: only destination_path is required, yet the description never explains how the source page is identified (path and locale vs page_id), which could lead an agent to invoke the tool with only a destination. The confirm-token two-step flow is also only discoverable in the schema, not flagged in the 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?

Schema description coverage is 100%, so the baseline is 3. The phrase "another path, another locale, or both" adds mild combination semantics for destination_path and destination_locale, but the description contributes no format, precedence, or identification details beyond what the schema already documents.

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 states a specific verb and resource: "Moves a page to another path, another locale, or both." It clearly delimits the operation's scope and distinguishes it from sibling tools like update_page (content editing), delete_page, and migrate_pages_locale (bulk locale migration). An agent can tell what this tool does and what it does not do.

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 gives explicit actionable guidance: "Internal links pointing at the old path are NOT rewritten by Wiki.js — check list_page_links first if that matters," naming the exact alternative tool and the condition that selects it. However, it offers no routing guidance versus other page-handling siblings (update_page, migrate_pages_locale), so exclusions are not comprehensive.

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?

Even though destructiveHint is already true, the description adds significant behavioral detail: versions are 'gone permanently', this is 'the one maintenance operation that destroys data', and a confirmation token is required. This goes well beyond the annotation and warns the agent about irreversible consequences.

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 short sentences each carry essential information: the action and scope, the permanent destructive nature, and the confirmation requirement. There is no filler, and the most important constraints are front-loaded.

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 destructive two-parameter tool, the description plus schema and annotations cover everything an agent needs: wiki-wide scope, cutoff semantics, token workflow, and permanence. Return-value details are presumably handled by the output schema, so nothing essential is missing.

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 input schema already fully documents both parameters, including the ISO-8601 cutoff options and the two-step confirmation-token flow. The description only refers generically to a 'cutoff' and 'confirmation token', adding no new parameter detail, so the baseline of 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?

The description states a specific verb and resource: 'Deletes stored page versions older than a cutoff, across the whole wiki.' This clearly distinguishes the tool from page-level operations like delete_page and from read-only history tools like list_page_history or get_page_version.

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: this is a wiki-wide maintenance operation for purging old page versions, not a per-page or inspection operation. It does not explicitly name alternatives or when-not-to-use conditions, but the destructive maintenance role is evident and unique among the sibling tools.

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?

Goes beyond the annotations by specifying that page content is untouched, that the operation walks every page, and that it can take minutes. This gives the agent realistic expectations about runtime and safety while remaining fully consistent with idempotentHint and destructiveHint.

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 compact sentences: what it does, when to use it, and the key side-effect/performance caveat. Every sentence earns its place, and the core action is front-loaded.

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 parameters, an output schema present, and annotations covering idempotence and non-destructiveness, the description supplies the essential operational context: the failure mode it fixes, common triggers, and the potential long runtime. Nothing critical is missing for an agent to select and invoke this tool correctly.

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 tool has zero parameters and the schema is an empty object, so there is nothing for the description to add about parameter semantics. The baseline of 4 applies because no parameter documentation is needed.

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 uses a specific verb and resource: 'recomputes the folder structure Wiki.js derives from page paths' and identifies itself as 'the repair' for a stale navigation tree. This clearly distinguishes it from read-only tree tools like get_page_tree and from other maintenance tools like rebuild_search_index.

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?

Clear trigger conditions are given: use it when the navigation tree disagrees with the pages actually present, typically after a bulk import or database edit. It does not explicitly name alternatives or when-not-to-use cases, so it falls short of a 5, but the context is strong.

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?

Beyond the annotations, the description discloses important behavioral traits: search silently returns nothing until this runs, results may be incomplete while it runs, and it can take minutes on large wikis. This adds substantial operational context that annotations do not convey.

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, each earning its place: the action, the required condition, and the side effects. No fluff, front-loaded with the core purpose.

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 no-parameter tool with an output schema present, the description fully covers purpose, when to run, side effects, and duration. Nothing an agent needs to decide whether and when to invoke it is missing.

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 tool has zero parameters, so the input schema provides nothing to describe. The description references the 'active search engine' as implicit context, which is all that is needed. Baseline for zero parameters is 4.

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 a specific verb and resource: 'Reindexes every page in the active search engine.' This clearly distinguishes the tool from maintenance siblings like rebuild_page_tree and from read-only search operations.

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 explicitly states when the tool is required ('Required once after switching away from Database - Basic') and when it is unnecessary ('On the basic engine it does nothing'). This provides clear when-to-use and when-not-to-use guidance without ambiguity.

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?

The description discloses a critical behavioral consequence beyond the annotations: pages embedding the asset by its old URL will break, and Wiki.js does not rewrite them. This is exactly the kind of side-effect context an agent needs. The destructiveHint=false annotation is not directly contradicted because the tool renames rather than destroys data; the breakage is an indirect consequence the description responsibly surfaces.

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 with no wasted words: the first states the core action, and the second delivers the essential warning. The most important operational caveat is front-loaded and easy to parse.

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 of this complexity, the description is complete: purpose, side effects, and the reason for the side effect are all covered. The output schema exists, and the input schema fully documents the confirmation-token mechanism, so nothing needed for correct invocation is missing.

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 100%, with all three parameters already documented in the input schema, including the confirm_token flow. The description adds no parameter-level detail, so the baseline score of 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?

The description opens with the specific verb-plus-resource statement 'Renames an asset,' which clearly identifies the operation and object. It is distinct from sibling tools like upload_asset and delete_asset, and the title 'Rename a file' is reinforced rather than merely restated.

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 does not name an alternative tool, but no sibling offers a rename operation, so this is acceptable. The warning that embedded pages will break provides an implicit when-not-to-use signal: avoid renaming if preserving old URLs matters. This is clear contextual guidance even without explicit exclusions.

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?

Beyond the annotations, the description discloses a crucial non-obvious side effect: rendering bumps the page's updatedAt, which can cause update_page to refuse a subsequent write based on stale-read detection. It also clarifies the safety profile ('Changes no content and cannot lose anything'), consistent with destructiveHint false, and explains recovery steps. This is exactly the kind of behavioral context annotations do not provide.

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 dense but every sentence earns its place: purpose, applicability, safety, side effect, failure mode, remedy, and best-practice ordering. The main purpose is front-loaded, and the caveat is explicitly separated, making the structure easy for an agent to parse.

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 single-parameter tool with rich annotations and an output schema, the description covers everything an agent needs: what the tool does, when to use it, what side effects it has, how it interacts with update_page and get_page, and how to recover from the generated conflict. There is no meaningful 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?

The only parameter, page_id, is fully documented by the input schema with a clear 'Numeric Wiki.js id' description. The tool description does not add parameter-level detail, but with 100% schema coverage the baseline of 3 is appropriate; nothing important about the parameter is missing.

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 a specific verb and resource: 'Forces Wiki.js to regenerate one page’s HTML from its source.' It also frames the exact problem this solves — stale rendering after a theme or renderer change — which clearly distinguishes it from read, write, and bulk-rebuild sibling tools such as get_page, update_page, flush_page_cache, and rebuild_page_tree.

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 states when to use the tool ('The fix for a page whose rendering is stale after a theme or renderer change') and gives explicit workflow guidance: render after writing rather than before, and if an update is refused, call get_page again and then write. It also names update_page and get_page as relevant alternatives, so an agent knows how the tool fits into a larger operation.

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 convey read/write and destructive behavior. The description adds useful side effects ('emails the user a link') and a non-obvious exclusion ('No password is chosen or returned'). However, the phrase 'Requires a confirmation token' is underspecified and could confuse agents, since the schema marks confirm_token as 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?

Three short, front-loaded sentences convey action, scope, and key exclusions without padding. 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?

With annotations, 100% schema coverage, and an output schema present, the description is nearly sufficient. The main gap is that the confirmation-token flow is not explicitly described as 'call once without it, then again with it,' which would eliminate ambiguity.

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 100%, so the schema fully documents both parameters. The description adds no meaningful parameter-level detail beyond what the schema already provides, though the 'no password' clause helps clarify the absence of a password parameter.

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 states a specific action ('Starts Wiki.js’ own password reset'), scopes it to local accounts, and explains what it does not do ('No password is chosen or returned here'). This clearly distinguishes it from direct credential-modification tools like update_user.

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 provides clear context: local account, email-based reset. However, it does not explicitly state when to use this versus alternatives, nor does it explain the two-step confirmation workflow. The mention of a confirmation token is present but vague.

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?

The description adds meaningful behavior beyond the annotations: it reveals that current content is preserved as history, that the live page is replaced, and that a confirmation token is required. This gives the agent a clear mental model of the destructive-but-recoverable nature of the operation, complementing the destructiveHint and readOnlyHint annotations.

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 focused sentences: the first states the action and the key lossless behavior, the second states the confirmation requirement. Every clause earns its place, and the most important behavioral fact is front-loaded.

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 that an output schema exists and the input schema fully documents all parameters, the description covers the remaining context: what happens to current content, what changes on the live page, and the mandatory token flow. Nothing essential is missing for an agent to invoke the tool correctly.

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 schema has 100% coverage for parameter descriptions, so the baseline is 3. The description only mentions the confirmation token concept, while page_id and version_id semantics are fully covered by the schema. It adds no additional parameter-level nuance.

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 uses a specific verb and resource: "Rolls a page back to a stored version." It also clarifies the key consequence, "the live page is replaced," which distinguishes it from related tools like get_page_version or update_page. The title and description align without being tautological.

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 usage — use it to revert a page to an earlier version — but it does not explicitly state when to use it versus alternatives like update_page, delete_page, or purge_page_history. No exclusions or alternative routing are provided, so the agent must infer context.

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 carry destructiveHint=true and idempotentHint=true, but the description still adds three distinct behavioral facts beyond them: permanent irrevocability, the self-inflicted risk of cutting the server's own connection, and the confirmation-token requirement. No contradiction with annotations.

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 short sentences, front-loaded with the core action and the irreversible consequence, followed by the two most important warnings. Every sentence earns its place; there is no filler or repetition of schema details.

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 destructive, two-step operation, everything essential is covered: what it does, irreversibility, the self-connection risk, and the token requirement, with flow details supplied by the schema and full parameter documentation present. Unstated items like permission requirements are minor given the rich annotations and output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.