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

Annotations already declare readOnlyHint=false and destructiveHint=false, which is consistent with the additive write behavior. The description adds genuinely useful behavioral context by stating that names are normalized to lowercase kebab-case, which affects how inputs are interpreted.

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 no filler. The primary action is front-loaded, and the normalization behavior is a relevant detail that 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 two-parameter write tool with annotations present and no output schema, the description covers the essential invocation details. It is only slightly incomplete in not addressing duplicate-name behavior or idempotency, but neither gap prevents a correct call in the common case.

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 only 50%, with names lacking a description. The description compensates by explaining that names are labels and that they will be normalized to lowercase kebab-case. page_id already has a schema description ('Page UUID or slugId'), so the description adds meaningful semantics where the schema is silent.

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 ('Add'), a concrete resource ('labels to a page'), and the scope ('one or more'). It is clearly distinguishable from the sibling tools list_page_labels and remove_page_label, which perform opposite 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 purpose clearly implies when to use the tool: whenever labels need to be added. However, it does not explicitly contrast with list_page_labels or remove_page_label, nor does it state any conditions where another tool should be used instead.

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 readOnlyHint=false and destructiveHint=false, and the description adds no behavioral context beyond the basic action. It does not disclose whether adding an existing member updates their role, whether at least one ID is required, what permissions are needed, or any side effects. Given the openWorldHint=true annotation, the lack of additional context is a noticeable 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?

A single sentence that is concise and front-loaded with the action and target. Every word earns its place; there is no redundancy or filler.

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 moderate complexity and absence of an output schema, the description is thin. It omits critical context such as idempotency, behavior when a member already exists, permission requirements, and the implication that user_ids/group_ids may be empty. The openWorldHint annotation suggests side effects that the description fails to explain.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 25% (only space_id is documented). The description maps 'users' to user_ids, 'groups' to group_ids, and 'role' to the role parameter, providing some semantic context. However, it does not clarify that at least one of user_ids or group_ids is expected, nor does it explain the behavior when both are omitted.

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 'Add' with a clear resource ('users and/or groups to a space') and includes the role qualifier. It is immediately distinguishable from sibling tools like remove_space_member and update_space_member_role, which address different 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 implies the usage scenario: when you want to add members to a space. However, it does not explicitly state when not to use it, mention alternatives, or clarify distinctions from related operations like updating roles. It provides only implied usage guidance.

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

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

Annotations already establish the safety profile: readOnlyHint=false (mutation), destructiveHint=false (source preserved), openWorldHint=true (external effects). The description adds the access-scoped behavior ('accessible sub-pages'), which is useful auth context, but it leaves partial-failure behavior unspecified — what happens to the copy if some sub-pages are inaccessible is not disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence opens with the verb and packs the object, sub-page scope, and destination into one clause with zero filler. 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 simple two-parameter tool with fully covered schema and no output schema, the core behavior is adequately described. The gap is edge-case behavior raised by the 'accessible' qualifier — partial copy vs. whole-operation failure — and the unspecified case where space_id equals the source space.

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 parameters are already documented (page_id as 'Page UUID or slugId', space_id as 'Destination space'). The description adds no parameter-level detail beyond the schema, matching the baseline of 3 for full coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Copy'), resource ('a page and its accessible sub-pages'), and destination ('a different space'). This implicitly distinguishes it from the move siblings and duplicate_page via the copy-vs-move verb and cross-space scope, though the differentiation is not made explicit.

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: copy (rather than move) a page tree into a different space, which hints at the line between this tool and move_page/move_page_to_space/duplicate_page. However, it never names alternatives or states when not to use it, so the agent must infer sibling selection purely from verb semantics.

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 this is a non-read-only, non-destructive operation, so the description is not required to repeat that. It adds useful context about page-level scope and the unsupported inline selection case. However, it does not disclose any further behavioral traits such as permissions, rate limits, or result behavior beyond what annotations cover.

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 no filler. The core action is front-loaded, and the important limitation about inline selection comments is stated directly. 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 simple create operation with a fully documented schema and annotations covering mutation safety, the description provides sufficient context: it names the object being created and an important limitation. It does not describe the return value or permissions, but given the tool's simplicity and annotation coverage, these are not critical gaps.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the input schema already documents all three parameters, including the purpose of parent_comment_id. The description does not add parameter-level details beyond the schema. This meets the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Add a page-level comment.' It also distinguishes the tool from inline selection comments, making the operation unmistakable. No sibling tool name is present, but the resource and scope are clear.

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 a clear context: use this tool for page-level comments, not inline selection comments. However, it does not explicitly mention alternative tools or conditions for choosing update_comment, delete_comment, or get_comments. The guidance is implied rather than explicit.

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

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

The description goes beyond the annotations by disclosing that the body is Markdown, is persisted 'in place', and notes a version dependency (Docmost v0.71+). This is useful behavioral context that the readOnly/destructive hints do not cover. 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?

Two short, information-dense sentences with no fluff. The primary action is front-loaded, followed by the two most behaviorally relevant details: Markdown persistence and parent nesting.

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 annotations and schema, the description covers the important aspects of creating a page. It does not mention return values or error cases, but no output schema exists and the tool is relatively simple. The version note and nesting detail make it sufficiently complete for invocation.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by clarifying that markdown is the body format and that parent_page_id enables nesting under a parent. It does not deeply explain icon/title semantics, but the schema already documents those adequately.

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 ('Create a page'), the resource ('in a space'), and adds distinguishing details: Markdown body, persistence behavior, and optional parent nesting. This separates it from sibling tools like create_space or create_comment 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 purpose is self-evident: use this to create a new page in a space, optionally under a parent. It provides clear context for when to invoke it, though it does not explicitly name alternatives or exclusions (e.g., update_page for modifying existing pages).

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 this is a non-read-only, non-destructive operation, and the description adds valuable behavioral context: slug auto-generation from the name when omitted and the permission requirement. It does not describe edge cases like duplicate slugs, but for a create tool the key behaviors are disclosed.

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 compact and front-loaded: the core purpose appears first, followed by two high-value behavioral details. Every sentence earns its place, and there is no redundant or filler 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?

For a simple three-parameter create operation with annotations covering safety, the description covers the main context: what it creates, how slug behaves, and the permission barrier. It does not specify return values or duplicate behavior, but these are not essential given the lack of an output schema and the self-explanatory nature of the operation.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the burden for parameter meaning. It adds meaningful semantics for slug by explaining it is generated from the name if omitted, but it does not explain the 'description' parameter or further clarify constraints on name. The parameter names are self-evident enough to keep this at an adequate rather than poor level.

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 'Create a space' with a specific verb and resource, making the tool's function immediately clear. It inherently distinguishes itself from sibling tools like update_space and delete_space, and the slug-generation detail reinforces the creation-specific 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 provides a useful prerequisite by noting that managing spaces requires permission, which helps the agent decide whether it can safely call the tool. However, it does not explicitly mention alternatives or when not to use this tool, so the usage guidance is implied rather than fully 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 declare readOnlyHint=false and destructiveHint=true, and the description aligns with these by describing a destructive delete operation. It adds meaningful behavioral context beyond the annotations by specifying the authorization model: owner-only for own comments, space-admin for any comment.

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 sentence that front-loads the core operation ('Delete a comment') and then adds the essential permission constraints. There is no irrelevant detail 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 one-parameter delete operation, the description covers the purpose and the relevant permission rules. It does not mention whether deletion is permanent or recoverable, but the destructiveHint annotation already signals destructiveness. Overall, the definition is sufficiently complete for an agent to select and 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 description does not mention comment_id at all, and schema description coverage is 0%, so the description was expected to compensate. The parameter is simple and self-descriptive from its name and UUID format, which prevents a score of 1, but no additional meaning is provided 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 clearly states a specific verb and resource: 'Delete a comment.' It also differentiates this from siblings like delete_page, create_comment, and update_comment by naming the comment as the target. The permission scoping further clarifies what this operation means.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when the tool is allowed: owners can delete their own comments, and space admins can delete any comment. It does not name alternative tools explicitly, but the deletion context is unambiguous, and the permission model helps an agent determine whether to attempt the call.

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 readOnlyHint=false, so the description's added value lies in detail beyond safety labels. It adds the crucial nuance that the default action is a trash move (recoverable in principle) while permanent delete is the truly destructive path, plus the auth requirement of space admin. It falls short only in not disclosing side effects on child pages or explicitly confirming trash is recoverable via restore_page.

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 primary behavior is front-loaded, and the permission caveat follows immediately. 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?

The essential decision (trash vs permanent) and the key prerequisite (admin) are covered, which is the core of what an agent needs to invoke the tool correctly. However, for a destructive tool with openWorldHint=true and no output schema, gaps remain: no mention that trashed pages are recoverable (restore_page sibling exists), no cascade effects on child pages or attachments, and no return-value note. Adequate but missing secondary context about the destructive footprint.

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 both parameters are already documented (page_id as UUID/slugId, permanently with default false). The description adds meaning by tying the space-admin requirement to the permanently=true path, a constraint not present in the schema. This is useful semantic context beyond what the structured fields 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 names a specific verb ('Move to trash' / 'permanently delete') and a specific resource ('a page'), making the operation unambiguous. The dual-mode behavior is stated up front, which distinguishes this tool from siblings like restore_page (the inverse operation) and move_page (relocation rather than deletion).

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 page needs to be removed) and gives one concrete constraint: permanent deletion requires space admin. However, it never names alternatives or exclusions — it does not point to restore_page for undoing a trash, nor delete_space for space-level deletion, even though those siblings exist. The guidance is adequate but relies on the agent to infer routing.

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

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

Annotations already mark this as destructive and non-read-only. The description adds meaningful behavioral disclosures: the entire space and its pages are affected, and the operation cannot be undone. This goes beyond the annotation hints 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 short sentences convey the action, scope, and irreversibility with no filler. The core destructive behavior 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 two-parameter destructive tool with a full schema and no output schema, the description covers the essential behavioral information: what is deleted and that it is irreversible. It lacks permission-level context and routing to alternatives, but these are minor given the low complexity.

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 both parameters already documented, including the confirm const true requirement and the space_id UUID or slug format. The description adds no parameter-specific details, 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 uses a specific verb ('Delete') and resource ('a space and its pages'), making the operation unambiguous. It also distinguishes itself from sibling delete_page by explicitly stating that pages within the space are deleted.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives like delete_page or restore_page. The name implies the scope, but the description does not provide context, prerequisites, or exclusions, leaving an agent to infer usage.

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=false, destructiveHint=false, and openWorldHint=true, so the description adds context by clarifying 'accessible sub-pages' and 'same space' scope. It doesn't disclose details about whether duplicates link to the original, naming conventions, or whether sub-pages are copied recursively with full fidelity—useful behavioral traits for a duplication tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, front-loaded with the verb 'Duplicate' and resource. Every word earns its place, and the 'accessible sub-pages' qualifier adds important scope without extra length.

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 straightforward single-parameter mutation tool with no output schema, the description is mostly adequate. However, it lacks guidance on the result (e.g., what is returned, whether a new page ID is provided) and doesn't mention potential pitfalls like duplicating into a space with conflicting slugs or permission requirements.

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% and the only parameter page_id is fully described as 'Page UUID or slugId'. The description merely reinforces that page_id identifies the page to duplicate, adding no new meaning like format requirements or edge cases 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?

Uses a specific verb 'Duplicate' with a clear resource ('a page and its accessible sub-pages') and scope ('within the same space'). Distinguishes from siblings like copy_page_to_space by noting the operation stays in the same space, but doesn't explicitly name alternatives like copy_page_to_space for cross-space duplication.

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?

Implies it is for duplicating pages in the same space, and the phrase 'accessible sub-pages' hints at permissions-based inclusion. But it doesn't explicitly state when to use this vs copy_page_to_space, move_page, or create_page, and gives no conditions like 'if you need a copy in another space, use copy_page_to_space instead.'

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 destructiveHint=false; the description adds useful behavior beyond that: it writes to output_path or a temp file, returns path and content type, and explains the zip vs. single-file behavior for include_children. No contradiction.

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 with no fluff; the core purpose is front-loaded and every sentence adds information an agent needs (destination, format behavior, return value).

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 five-parameter tool with no output schema, the description provides the key missing context: where the file goes, what is returned, and how include_children changes the result. It remains slightly incomplete on include_attachments and default boolean behavior.

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 only 40%, so the description needs to compensate. It adds meaningful meaning for include_children (zip behavior) and output_path (temp fallback), but does not clarify include_attachments or how format interacts with include_children.

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 ('Export a page') and destination ('to a local file'), and clarifies output shape (.md/.html vs zip). This clearly distinguishes it from sibling tools such as export_space.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to choose export_page over alternatives like export_space or get_page. The conditional information about include_children is behavioral rather than tool-selection 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, non-destructive behavior, and the description adds useful behavioral details: the output is written to a caller-specified path or a temp file. This goes beyond the schema by explaining how results are delivered, though it does not mention overwrite behavior or temp-file lifecycle.

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 no filler. The core action and output format are front-loaded, and the output-delivery detail is placed second.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should clarify what the caller receives, especially when a temp file is used, but it does not mention the return value or how to locate the exported file. It also omits behavior for include_attachments and any default values for optional parameters, leaving important gaps for a tool with four 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 description coverage is only 25%, so the description must compensate. It adds meaning for format ('Markdown or HTML') and output_path ('or a temp file'), but include_attachments is left entirely undocumented, and no default behavior for format or attachments is provided.

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 operation (export), the resource (a whole space), and the output format (a zip of Markdown or HTML). It also distinguishes itself from the sibling export_page by the explicit 'whole space' scope.

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 wording implies the tool is for exporting an entire space rather than an individual page, which provides some context. However, it does not explicitly mention export_page as the alternative for single-page exports or state when not to use this tool.

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 destructiveHint=false, so the basic safety profile is covered. However, the description adds no behavioral detail beyond the annotations, such as what metadata is returned, whether the attachment must exist, or any auth/availability considerations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no filler. Every word contributes to identifying the action and resource, making it appropriately concise for a simple getter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter, read-only metadata retrieval tool, the description conveys the core purpose adequately. However, it omits any detail about what 'metadata' includes or when to prefer this over the attachment search/upload siblings, leaving moderate gaps.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description should compensate by explaining the parameter meaning. It does not add any detail beyond the schema's attachment_id field, though the parameter itself is fairly self-explanatory.

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 ('Get') and resource ('metadata for an uploaded attachment'), making the tool's function clear. It is reasonably distinguishable from siblings like upload_attachment and search_attachments, though it does not explicitly name or contrast them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives such as search_attachments, nor any mention of prerequisites like needing a known attachment_id. The usage context is only implied by the parameter schema, not explained.

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, destructiveHint=false, and openWorldHint=true. The description 'List incoming or outgoing page links' is consistent with these and adds minimal behavioral context. It does not contradict the annotations, but it also does not disclose details like pagination behavior or response structure beyond what the schema already implies.

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 five-word sentence that starts with the verb and resource. There is no fluff, filler, or redundancy. Every word contributes to the meaning, making it an exceptionally concise and well-structured definition.

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 is simple, and the schema + annotations cover parameters and safety profile. However, with no output schema, the description does not describe what the returned link objects contain, nor does it mention pagination explicitly. The cursor parameter referencing 'meta.nextCursor' hints at the response shape, but the description itself is minimal.

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 all four parameters (page_id, direction, limit, cursor) are already documented. The description adds little semantic value beyond restating the direction concept that the enum already captures. Baseline 3 applies 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 uses a specific verb, 'List', and identifies the resource as 'incoming or outgoing page links'. This clearly distinguishes it from sibling tools like get_page, get_page_history, and get_breadcrumbs, which focus on content, history, or navigation context rather than links.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance about when to use this tool versus alternatives. The usage context is implied by the name and phrase 'page links'—an agent can infer it is for retrieving link relationships—but no exclusions or alternative conditions 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds useful context about the path starting at the space root, but it does not disclose potential edge cases such as behavior for nonexistent page IDs or whether the page itself is included in the returned path. This is acceptable given the read-only, open-world hints, but the description carries only moderate additional value.

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 sentence that immediately states the action and resource with no extraneous words. It is front-loaded and every word contributes to the meaning. This is an exemplar of conciseness.

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 fully documented parameter and no output schema, the description provides enough context to understand the core behavior and return value ('ancestor path'). The annotations cover safety and open-world assumptions. Minor gaps remain, such as the exact ordering of the path or whether the target page itself is included, but these are low-stakes for an agent invoking the 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?

The input schema documents page_id as 'Page UUID or slugId', which fully explains the parameter. With schema description coverage at 100%, the tool description adds no extra parameter-level meaning. The baseline score of 3 is appropriate because the schema already handles the semantic 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 uses a specific verb 'Get' and names the exact resource: 'ancestor path from space root to a page'. This clearly distinguishes it from sibling tools like get_page or list_child_pages, which address different page relationships. No ambiguity remains about what the tool does.

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: whenever the ancestor path or breadcrumb trail from the space root to a specific page is needed. However, it does not explicitly mention alternatives or state when not to use it. Since no sibling tool directly competes with this function, the implicit guidance is adequate but not fully 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 establish readOnlyHint and non-destructive behavior. The description adds useful behavioral detail beyond those: content comes back as Markdown and each comment is re-fetched so results are not stale. This gives the agent a clearer expectation of output format and freshness without contradicting 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 short sentences with no filler. The core action is front-loaded, and the added behavior (Markdown output, freshness) each 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 read-only list tool, this is nearly complete: the description covers scope, return format, and freshness, and the schema covers pagination. Without an output schema, a bit more detail on the response envelope would make it fully self-contained, but 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?

Input schema coverage is 100%, with page_id, limit, and cursor all described in the schema. The description does not add parameter-level meaning, so the baseline score 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 opens with 'List page-level comments', a specific verb and resource that clearly defines a read operation. It distinguishes this tool from the sibling comment tools create_comment, update_comment, and delete_comment, and from other page 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 action 'List' and the required page_id imply it should be used to retrieve comments for a page, but no explicit when-to-use guidance or exclusions are given. There is no competing comment-listing sibling, so ambiguity is low, but the guidance is only implied.

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 destructiveHint=false. The description adds meaningful behavioral context beyond the annotations by specifying exactly what information is returned: authenticated user, workspace context, detected version, and read-only session status. There is 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?

A single sentence that front-loads the verb and resource, then enumerates the exact return items with no filler or repetition. 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?

With zero parameters and no output schema, the description fully specifies what the agent can expect: user, workspace context, version, and read-only status. Combined with the read-only annotations, there is no missing operational or safety 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?

This tool has zero parameters and schema description coverage is 100%, so there are no parameter semantics to clarify. The baseline of 4 applies because the description adds value by explaining the return scope, though it does not document 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 uses a specific verb ('Get') and clearly identifies the resources: authenticated user, workspace context, detected Docmost version, and read-only session status. This distinguishes it from all sibling tools, none of which target the current session context.

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 tool's purpose and context clear: it is for retrieving the current user/session context. It does not explicitly name alternatives or exclusions, but with zero parameters and a self-contained scope, the usage context is unambiguous 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=true and destructiveHint=false, so the read-only nature is fully covered. The description adds no further behavioral details, such as behavior for an invalid history ID or what fields the returned version contains, but nothing contradicts 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?

One short, front-loaded sentence contains all essential information with no filler. Every word contributes to the meaning, making it highly scannable for an agent.

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 fetch with strong annotations, the description is adequate and clear. The only notable gap is the absence of any return-value description, which matters more because there is no output schema to fill that 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 sole parameter history_id is fully documented in the schema as 'History version UUID', and the description repeats the 'by history ID' concept without adding format or usage details. With 100% schema coverage, 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?

Clearly states the operation ('Get'), the resource ('specific page history version'), and the lookup key ('by history ID'). This distinguishes it from the sibling get_page_history, which retrieves a page's history list rather than a single 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?

No guidance on when to use this tool versus alternatives such as get_page_history (for listing versions) or restore_page (for restoring a version). The description merely states the action without any context, exclusions, or 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 declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds return-format behavior (markdown default, json yielding raw ProseMirror), which is some value beyond structured data. It does not add context about auth requirements, trashed pages, or output shape, so it stays at a 3.

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?

Exactly two sentences with zero waste: the first states the core function and the second gives the highest-value usage hint. Both earn their place and the key scoping 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 simple read tool with 2 parameters, strong safety annotations, and no nested objects, the description covers what is returned (metadata, Markdown body, raw ProseMirror). The minor gap is that 'metadata' is undefined — the agent doesn't know which fields are included — and the html format option is left to inference. Still, 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%, so the baseline is 3. The description adds one meaningful nugget beyond the schema: 'Use format=json for raw ProseMirror' clarifies what the json enum value actually returns, which helps an agent pick the right format for downstream editing tasks. The page_id semantics (UUID or slugId) remain fully covered by 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: 'Get a page's metadata and Markdown body.' This is clear and substantive, and the return-value specificity ('metadata', 'Markdown body', 'raw ProseMirror') helps distinguish it from siblings like get_page_history, get_breadcrumbs, and get_backlinks. However, it does not explicitly name or contrast any sibling, so it stops short of a 5.

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 format tip 'Use format=json for raw ProseMirror' provides some usage guidance for choosing an output format, which is genuinely useful. But the dimension asks about when to use this tool versus alternatives, and the description offers no exclusions or alternatives (e.g., when to prefer export_page or get_page_history). Usage is only implied by the read-oriented verb and resource.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no additional behavioral context, such as ordering of revisions, whether deleted revisions are included, or what fields each history item contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no filler. It loses a point only because it is so terse that it carries no information beyond the tool's obvious purpose, though the brevity itself is appropriate.

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 list operation with well-documented parameters and safety annotations, the description is minimally adequate. However, there is no output schema and no mention of return shape, ordering, or pagination behavior beyond the cursor parameter, so an agent navigating history data would need more context.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters. The description does not add parameter-level meaning beyond 'page' scope, but it doesn't need to; 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 states a clear verb ('List') and resource ('revision history for a page'), and the plural 'history' distinguishes it from the singular get_history_version sibling. However, it doesn't explicitly call out that distinction or mention what a history entry contains, so it falls just short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance is provided. The description does not mention get_history_version or any other alternative, nor does it give conditions for when list vs. get history is appropriate, leaving the agent to infer from sibling names.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds one useful behavioral detail—that the result includes the current user's membership—but does not disclose failure behavior, required permissions, or what 'details' generally includes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence that states the main action and the notable membership detail with no filler. 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 simple read-only tool with one fully documented parameter and strong safety annotations, the description is nearly sufficient. The only notable gap is the lack of an output schema and no enumeration of which 'details' are returned, but an agent can still invoke it correctly with just the space_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?

The input schema fully documents space_id as 'Space UUID or slug' with 100% coverage. The description adds no additional parameter semantics 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 ('Get') and resource ('space'), and narrows the scope to a single space plus the current user's membership. It is clear, though it does not explicitly name or contrast sibling tools such as list_spaces or list_space_members.

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 context is clear: use this tool when you need details for one space, including the current user's membership. It does not explicitly mention alternatives or exclusion conditions, but the singular 'a space' implies the single-item retrieval use case.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond those annotations: it lists only direct children (not descendants) and preserves sidebar order. It also explains the space-root behavior, which is a non-obvious call pattern.

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 zero filler. The core purpose is front-loaded, and the conditional usage guidance is placed immediately after. 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 read-only list operation, the description captures the essential behavior, ordering, and the special root-page case. Pagination is covered by the schema's cursor and limit descriptions. No output schema exists, so an agent might not know the exact return shape, but the tool's purpose is simple enough that this is a minor gap rather than a critical omission.

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 limit and cursor are already documented. The description adds value by clarifying the relationship between page_id and space_id, specifically that space_id is used for root pages while page_id is omitted. This is a semantic decision rule not 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 clearly states the verb ('List'), the specific resource ('direct child pages of a page'), and an important behavioral detail ('in sidebar order'). This distinguishes it from broader tools like list_pages and get_page without needing to open 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 for the space-root case: 'Omit page_id and pass space_id for space-root pages.' This is a clear contextual usage rule. It does not explicitly name alternatives or say when not to use the tool, but the direct-child scope makes the intended use reasonably 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 declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds no extra behavioral context such as pagination behavior or whether the result set is limited to explicitly assigned labels, so it meets but does not exceed what annotations 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 a single front-loaded sentence with no filler or redundant wording. It is exactly as long as needed for a simple list operation.

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 schema documents all parameters and the annotations cover the read-only, non-destructive nature, so the core calling context is present. However, with no output schema, the description does not clarify the return shape or pagination mechanics beyond the cursor hint in the parameter schema. It is adequate for a simple list tool but leaves several details implicit.

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 limit, cursor, and page_id are fully documented in the schema. The description does not add any parameter semantics beyond what the schema already provides, matching the baseline expectation.

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 clear verb ('List') and a specific resource ('labels on a page'), so an agent can infer the operation. It does not explicitly differentiate from add_page_labels/remove_page_label, though the read verb itself distinguishes it from those write siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the natural use case—retrieve labels for a page—but gives no explicit when-to-use or when-not-to-use guidance. It does not point to add_page_labels/remove_page_label as the corresponding write operations, leaving the agent to infer selection from the verb.

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 destructiveHint=false, and the description adds genuinely useful context: the default recent view is not the sidebar tree and may make a space look empty. It also clarifies the meaning of the view parameter in behavioral terms. No contradictions.

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, tightly packed with signal and no filler. The most important caveat about default behavior is front-loaded, and the alternative tool is named without extra prose.

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 list tool with fully documented parameters and safety annotations, the description covers the key edge cases (empty-looking space, sidebar tree vs recent) and routes to the right sibling. 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 coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the default value of view and the behavioral difference between recent and tree, which is the key semantic distinction among 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?

States a specific action and resource: 'List pages in a space.' It differentiates the two views, recent vs tree, and explicitly names the sibling list_child_pages, so an agent can distinguish this tool from closely related page-listing 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?

Gives explicit conditional guidance: default view=recent for recently updated pages, view=tree for space-root pages in sidebar order, and list_child_pages for children of a page. This tells the agent exactly when to use each variant and when to prefer a sibling tool.

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 destructiveHint=false, so the safe-read nature is covered. The description adds only that groups are included, which is more of a scope detail than a behavioral trait. It does not disclose pagination, permission requirements, or return shape, but the annotations lower the burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, direct sentence that front-loads the core action and resource. Every word earns its place, and there is no redundancy or filler.

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 complete schema parameter documentation and safety annotations, the description is mostly sufficient. It could mention pagination or the return format, but the schema already covers cursor and limit, and the annotations cover behavioral safety. The scope of 'members and groups' is clearly stated.

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 limit, cursor, and space_id all documented. The description adds no parameter-specific meaning beyond the schema, 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 uses a specific verb ('List') and a clear resource ('members and groups in a space'). It is immediately distinguishable from sibling tools like add_space_members, remove_space_member, and update_space_member_role, and the phrase 'in a space' separates it from list_workspace_members.

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: whenever you need the members and groups of a specific space. It gives clear context but does not explicitly mention alternatives or state when not to use it, such as pointing to list_workspace_members for workspace-level membership.

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 destructiveHint=false. The description adds the useful behavioral constraint that results are scoped to the authenticated user's access, which goes beyond the annotations. It does not contradict the annotations or describe destructive behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no filler. Every word earns its place: 'List' states the action, 'spaces' the resource, and 'the authenticated user can access' the scope.

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 well-documented pagination parameters, the description plus annotations and schema fully cover what an agent needs to select and invoke it. No output schema exists, but the meaning of 'List spaces' is unambiguous.

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 (limit, cursor) are documented in the schema. The description adds no parameter-specific information, but per the rubric the baseline of 3 applies when schema coverage is high.

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 ('List'), a clear resource ('spaces'), and a well-defined scope ('the authenticated user can access'). This differentiates it from siblings like get_space (single space) and list_pages (pages, not spaces).

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 the goal is to enumerate accessible spaces. It does not explicitly name alternatives or exclusions, but the context is clear enough that an agent would not confuse it with mutation tools like create_space or delete_space.

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 destructiveHint=false, so the read-only safety profile is covered. The description adds the important scope that only soft-deleted pages are returned, but it does not mention output shape, ordering, or pagination behavior beyond what the schema already implies.

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, tight sentence with no filler. The verb and object are front-loaded, and 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 simple read-only listing tool with one required parameter and fully documented optional pagination parameters, the description is sufficient for correct invocation. It could be slightly stronger with a pointer to related tools or return-value expectations, but 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?

Schema description coverage is 100%, so limit, cursor, and space_id are already documented in the input schema. The description adds no extra parameter-level meaning except reinforcing that the listing is scoped to a space.

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 a specific verb (List), a specific resource (soft-deleted pages), and a scope (in a space). It distinguishes itself from list_pages by the 'soft-deleted' qualifier, though it does not explicitly name an alternative tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'soft-deleted pages' implies when to use this tool—when the agent needs trash contents rather than active pages. However, there is no explicit guidance about when to prefer a sibling tool like list_pages or restore_page, and no exclusion 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 cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description adds no new behavioral context. It does not mention pagination behavior, ordering, or response format, even though the schema's cursor and limit parameters imply pagination.

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, focused sentence with zero filler. It is front-loaded with the action and resource, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and only a terse description, the agent is left without information about return shape, pagination metadata, or how this differs from list_space_members. For a list endpoint with optional pagination parameters, more context is needed for confident 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%: each parameter (limit, query, cursor) has a clear description. The main description adds nothing beyond the schema, so the 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 ('List') and resource ('workspace members'), clearly identifying the operation. It does not explicitly contrast with the sibling tool list_space_members, so sibling differentiation is left to inference from the resource word 'workspace'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided about when to use this tool versus alternatives such as list_space_members, list_spaces, or get_current_user. The description only states the action with no context, exclusions, or prerequisites.

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 that this is a mutating but non-destructive operation. The description adds a useful behavioral detail: position is computed by default unless an explicit 5-12 character key is passed. It doesn't disclose side effects, permissions, or what happens to child pages, but the annotation coverage lowers the burden.

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 fluff. The main action and destination are front-loaded, and the position nuance is stated in the second sentence without repeating 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 five-parameter tool with full schema coverage and no output schema, the description gives the essential high-level behavior and position semantics. It doesn't explicitly mention after_page_id or compare against move_page_to_space, but the schema covers the remaining parameter semantics well enough 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%, so the baseline is 3. The description adds genuine semantic value by explaining that position is computed unless an explicit fractional-index key is supplied, and by framing parent_page_id/root as the two destination modes.

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 ('Move') and resource ('a page') and clearly distinguishes the two main destinations: a new parent or the space root. This differentiates it from the sibling move_page_to_space, which implies moving to a different space.

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 implied usage context: the tool is for reparenting a page or moving it to the space root, and position is computed unless an explicit key is provided. However, it never explicitly says when to choose this over move_page_to_space or other siblings, so the guidance is partial.

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 communicate that the operation is a mutation and not flagged destructive; the description adds a meaningful behavioral nuance by stating that only 'accessible' sub-pages are moved, which is not present in the schema or annotations. It does not discuss permission requirements or return behavior, but with annotations covering the safety profile this is acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no filler. Every word carries meaning: the action, the scope (page and accessible sub-pages), and the destination (different space).

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 two-parameter move operation, the core call parameters and scope are covered, and the accessible-sub-pages caveat is important. The only notable gap is that with no output schema the description does not state expected return values or error conditions, but this does not block 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 coverage is 100% and both parameters already have descriptions ('Page UUID or slugId' and 'Destination space'), so the baseline applies. The description adds no new parameter-level detail beyond reinforcing that the destination is a space.

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 ('Move') with a specific resource ('a page and its accessible sub-pages') and destination ('to a different space'). It clearly distinguishes this from copy_page_to_space and from move_page by emphasizing the cross-space destination and the sub-page scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'to a different space' gives implied context for when this tool is appropriate, but there is no explicit when-to-use/when-not-to-use guidance and no reference to alternatives such as move_page or copy_page_to_space. An agent must infer the routing from sibling names.

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

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

Annotations already indicate this is a mutation (readOnlyHint: false) and not destructive (destructiveHint: false). The description adds the concrete semantics of removing a label association, but it does not explain side effects such as whether the label itself is deleted or whether removal is idempotent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single clear sentence states the action, target, and required identifier with no filler. It is well-structured and 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 simple two-parameter mutation tool, the description plus schema provides enough information to call it correctly. Missing details like error behavior or confirmation that the label itself is not deleted are minor given the simple scope and available annotations.

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 only 50% because label_id lacks a description, but the phrase 'by label ID' supplies the semantic role for that parameter. page_id is already documented in the schema as 'Page UUID or slugId', so the description does not add much beyond confirming the label_id usage.

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 ('Remove'), a specific target ('a label from a page'), and the key input ('by label ID'). This clearly distinguishes it from sibling tools like add_page_labels and list_page_labels.

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 conveys when to use the tool implicitly by describing the operation, but it does not explicitly name alternatives or state when not to use it. An agent can infer usage from the verb, but no direct routing guidance is provided.

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 no behavioral context beyond what annotations already declare. It doesn't explain consequences of removal, permission requirements, reversibility, or effects on the member's access, which is relevant given destructiveHint=true.

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?

One short sentence with the operation and target front-loaded, and no filler. Both halves of the description earn their 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 destructive tool with no output schema and sparse parameter metadata, the description is too thin. It omits the relationship between user_id and group_id, the success/return behavior, and the practical implications of removing a member.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 33%, and the description does not compensate. It says 'user or group' but does not clarify whether user_id and group_id are mutually exclusive, whether at least one is required, or what happens if both or neither are supplied.

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 ('Remove') and resource ('a user or group from a space'), making the core operation unambiguous. It is clearly distinct from siblings like add_space_members or update_space_member_role, though it does not explicitly name an alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus sibling membership tools, and no exclusions or prerequisites are given. The intended usage must be inferred entirely from the verb and tool name.

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 this is a mutating operation (readOnlyHint=false) that is not destructive (destructiveHint=false). The description adds the useful precondition that the page must be soft-deleted and in trash, but it does not disclose error behavior, permission requirements, or side effects such as conflicts with existing pages. This adds some but not rich 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 a single, well-structured sentence that front-loads the operation and its precondition. Every word contributes to understanding, 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?

For a single-parameter tool with clear annotations and no output schema, the description is sufficient for an agent to select and invoke it correctly. Minor omissions such as exact error behavior are not essential for correct usage.

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 the only parameter, page_id, including accepted forms ('Page UUID or slugId'). The tool description adds no additional parameter semantics, so the baseline 3 applies because the schema already carries the burden.

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: 'Restore a soft-deleted page from trash.' This clearly distinguishes it from inverse operations like delete_page and from list_trash, leaving no ambiguity about the tool's 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 context by specifying that the page must be soft-deleted and in the trash, which tells an agent when the tool is appropriate. It does not explicitly name alternative tools or exclusion criteria, 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context about the Enterprise-only restriction and the 403 failure mode, which is beyond what annotations capture. It does not go into pagination or indexing details, but the annotation coverage lowers the burden.

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 adding distinct value: functionality, licensing constraint, and routing to an alternative. No redundant phrasing or schema 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?

The description covers the main functional, licensing, and alternative-selection context. There is no output schema, but for a read-only search tool the behavior is sufficiently clear. Minor gaps like pagination defaults or result shape are not critical given the annotations.

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 required query parameter has no schema description, but the tool description fills that gap by explaining it searches by name or indexed text. The optional limit and space_id parameters are already described in the schema, so the description need not repeat them.

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: 'Search file attachments by name or indexed text.' It also differentiates from the sibling get_attachment_info, making the tool's purpose 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 explicitly states that this is an Enterprise feature, warns that Community Edition returns 403, and tells the agent to prefer get_attachment_info when an attachment id is already available. This provides clear when-to-use and 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=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context that only accessible pages are searched and that space scoping is possible. It does not describe search syntax, ranking, or pagination behavior, which would add further value, but it does not contradict 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 a single, front-loaded sentence that states the primary action and resource immediately, then adds the optional scoping nuance. There is no filler or repetition of schema information, making it highly concise 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 search tool with four well-documented parameters and annotations covering safety and open-world behavior, the description is nearly complete. It effectively communicates the access scope and optional space filter. The only small gap is that it does not describe result details such as ordering or returned fields, but no output schema exists and the description is sufficient 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 every parameter already has a meaningful description (query, limit, offset, space_id). The description's mention of optional space scoping aligns with space_id but adds no new parameter semantics beyond the schema. Baseline 3 is appropriate when the schema carries the full parameter documentation.

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 ('Full-text search') with a clear resource ('pages') and defines the access boundary ('the authenticated user can access'). It also notes optional scoping to a space, which differentiates it from sibling tools like search_attachments and search_suggest without opening their 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 clearly establishes the core use case: searching for pages, not attachments or other resources. It also describes the optional space scoping feature, giving useful context for narrowing a search. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavior beyond annotations: pages are included by default, users/groups are off by default, and include_pages=false is the way to skip pages. This explains real default filtering behavior that the schema does not fully 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?

The description is two short sentences with no filler. The core purpose is front-loaded, and the second sentence efficiently conveys the most important default-toggle behavior. Every word contributes to usable guidance.

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 suggestion tool with six mostly self-explanatory parameters, annotations covering safety, and no output schema, the description is nearly complete. It explains the key defaults but does not describe the return value structure or explicitly mention space scoping, which would make it fully self-sufficient.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 50%, and the description partially compensates by explaining the default states of include_pages, include_users, and include_groups. However, it does not clarify how space_id scopes suggestions, what the limit controls beyond 'page size,' or the matching semantics of query, so the agent still has to infer some parameter behavior.

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 begins with 'Typeahead suggestions,' which clearly identifies the tool as returning lightweight suggestion results for autocomplete-style queries. It distinguishes from sibling search tools like search_pages and search_attachments by implying real-time, partial-match suggestions, though it does not use an explicit verb like 'returns' or 'lists.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Typeahead suggestions' establishes the tool's intended context: use it when you need progressive suggestions as the user types. It does not explicitly name alternatives such as search_pages for full result searches, so it stops short of full when-not guidance, but the typeahead framing is clear enough for selecting this tool over broad 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 readOnlyHint=false and destructiveHint=false, covering the mutation safety profile. The description adds useful behavioral context by specifying 'replace' (full overwrite semantics) and the ownership constraint, but it does not disclose what happens if the comment is not found or not owned, nor does it address the openWorldHint=true implication of possible broader 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 short sentences with no filler. The primary action is front-loaded ('Replace a comment body.'), and the ownership context is given in the second sentence. 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 simple two-parameter tool with annotations, this is minimally viable. However, there is no output schema and no mention of return value, error behavior, or explicit parameter mapping. The ownership restriction is stated, but the tool description does not fully equip an agent to anticipate failure modes or response formats.

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 needs to compensate. It only implies that markdown is the new body and comment_id selects the comment; it does not explicitly describe either parameter's role or format. The property names are somewhat self-explanatory, but the description adds minimal semantic value beyond the schema itself.

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 ('replace') with a clear resource ('comment body'), immediately distinguishing it from create_comment, delete_comment, and get_comments. Adding 'You can update your own comments' further clarifies the intended scope, so an agent can accurately identify the tool's function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'You can update your own comments' implies when it is appropriate to use the tool (editing your own comments) and hints at a restriction, but it does not explicitly contrast with create_comment or delete_comment, nor does it state conditions like 'use this instead of X'. The guidance is present but underdeveloped.

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, it reveals that body writes depend on a server converter version (v0.71+) and that operation defaults to 'replace', which is actionable behavioral context. It does not explicitly warn that replace overwrites the existing body, but the schema already defines the enum.

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 identifies the operation and scope, the second adds a critical version constraint and default behavior. 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 five-parameter update operation with annotations and a fairly descriptive schema, this is nearly sufficient. Minor gaps remain around expected return value and overwrite caveats, but an agent can determine how to invoke it 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 60%, and the description adds context for markdown (server conversion, default operation) while mapping title/icon indirectly. However, it does not elaborate on icon/title formats or page_id semantics beyond the schema, so the compensation is partial.

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 and resource ('Update a page') and enumerates the exact fields changed (title, icon, Markdown body). The phrase 'in place' differentiates this from sibling move/duplicate/copy 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 implies use for modifying an existing page rather than creating, moving, or deleting it, but it does not state explicit when-to-use conditions or name alternatives. 'In place' is a weak exclusion for the page-manipulation 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 readOnlyHint=false and destructiveHint=false, but the description adds no behavioral context beyond that. It does not disclose partial-update semantics, whether at least one optional field is required, slug uniqueness risks, or side effects like changing a space's URL.

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 concise sentence with no filler, and it front-loads the verb and target resource. Every word earns its place, even though the brevity contributes to missing context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with sparse annotations, low schema coverage, and no output schema, this description is incomplete. An agent cannot determine whether a successful update returns the updated space, whether unspecified fields are preserved, or what constraints like slug uniqueness apply.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 25% (only space_id is described). The description enumerates name, slug, and description but adds no meaning beyond their names; it does not clarify what a slug is, the relationship between space_id and slug, or that the fields are individually optional.

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 the specific verb 'Update' and identifies the exact resource and mutable fields: space name, slug, and description. It is clear in scope and distinguishes itself from sibling tools like update_space_member_role by focusing on space metadata, though it does not explicitly name alternatives.

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 guidance on when to use this tool versus alternatives. It does not mention update_page for page metadata, update_space_member_role for membership changes, or create_space/delete_space for lifecycle operations. Usage context is only implied by the tool name and sibling list.

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

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

With readOnlyHint=false and destructiveHint=false already present, the description adds no behavioral context beyond what annotations provide. It does not explain whether this is an overwrite, whether it requires special permissions, or whether the change can be reverted. No contradiction exists, but the description carries little additional transparency burden.

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 with no filler or redundant wording. It is front-loaded with the action and resource. Conciseness is excellent, though this does not compensate for missing semantic guidance.

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 low schema coverage, no output schema, and no usage guidance, the description is incomplete for safe and correct invocation. An agent cannot determine how to specify a member versus a group, whether one of user_id/group_id is required, or what the result/effects of the change will be. The description only provides the basic purpose.

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 only 25% parameter description coverage, and the description does not compensate. It says the target can be a member or group, which loosely maps to user_id and group_id, but it does not clarify that exactly one of these should be provided, nor does it explain the relationship to the required space_id and role. The enum on role is already structured in the schema, so the description adds minimal parameter-level value.

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 'Change a space member or group's role.' clearly states the action (change), the resource (space member/group), and the attribute affected (role). It is specific enough to distinguish from the sibling tools like add_space_members or remove_space_member, though it does not explicitly name an alternative.

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 about when to use this tool versus add_space_members, remove_space_member, or update_space. There is no mention of prerequisites, such as the need to provide either user_id or group_id, or any exclusions. Usage is only weakly implied by the phrase 'change ... role'.

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 that this is a mutating operation (readOnlyHint=false) yet non-destructive (destructiveHint=false). The description adds useful return-value context by stating that attachment metadata, including the /api/files/:id/:name URL, is returned, though it does not mention permissions or size limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that fronts the action, names the target, and includes the key return detail. Every word contributes value and there is no 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 simple two-parameter upload tool with fully documented parameters and no output schema, the description adequately covers the action, target, and return value. An agent can call this correctly with the information provided.

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%, with both page_id and file_path documented. The description's 'local file' and 'to a page' wording adds no meaningful information 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 plus resource: 'Upload a local file to a page.' This clearly distinguishes the tool from attachment-related siblings like get_attachment_info and search_attachments, which query rather than create.

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 a clear context for use: uploading a local file to a page. It does not explicitly name alternatives or exclusion conditions, but the action is straightforward and clearly different from the sibling read/query tools.

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