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

Annotations already mark this as a non-read-only, non-destructive mutation, and the description adds two facts annotations cannot convey: the required role (workspace admin or owner) and that existing roles are preserved on reactivation. It stops short of noting idempotency or behavior when the user is already active.

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 core sentence plus a short permission clause, with the effect front-loaded and zero filler. Every phrase carries information.

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

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

With an output schema present and a fully documented single parameter, the description supplies what structured fields cannot: the permission requirement and the role-preservation guarantee. Only edge-case behavior (already-active user, failure modes) is left out, which is a minor gap for a one-parameter tool.

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

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

Schema coverage is 100% and the single 'user' parameter is fully documented in the schema as email or user id. The description adds no additional parameter guidance, which is the expected baseline when the schema does the work.

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?

Specific verb+resource: re-enable sign-in for a previously deactivated person, and it names the counterpart tool (deactivate_member) so the pair is unambiguous against 50+ siblings. The added detail that roles are restored 'as before' further pins down the effect.

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

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

Explicitly scopes the tool to people deactivated via deactivate_member and states the permission prerequisite (workspace admin or owner). It does not say what to do for never-activated users or non-deactivated targets, so a minor inference remains.

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, and the description adds real side-effect context the annotations cannot: comments are visible to everyone who can see the page, and mentioned users are notified by Docmost. It does not state permission requirements for commenting or what happens on an invalid page id, leaving a small 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?

Two sentences, front-loaded with the core action and reply variant, then visibility and mention etiquette. The mention guidance is slightly longer than strictly necessary but every clause carries actionable information, so nothing is wasted.

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 full schema coverage, an output schema, and annotations present, the description supplies the missing behavioral layer (visibility, notifications, mention placement). Complete enough to call correctly; only authorization/prerequisite context is absent.

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

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

Schema coverage is 100%, so baseline is 3, and the description genuinely adds meaning: it specifies that mentions are placed at the start of the comment and trigger notifications, and that reply_to_comment_id turns the call into a threaded reply. It does not explain the accepted formats for `page` (id/slug/URL) beyond what the schema already says, but that is already covered.

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

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

States a specific verb and resource ("Add a comment to a page") and immediately covers the second mode (reply via reply_to_comment_id), so an agent knows both shapes of the operation. It never names update_comment or list_comments, so the differentiation from sibling tools is left implicit.

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?

"mention someone only when they need to act on it" gives explicit conditional guidance for the optional mention parameter, and the reply_to_comment_id clause tells the agent how to switch into reply mode. There is no stated exclusion (e.g., when to prefer update_comment instead of adding a new one), so it falls 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 this is a non-destructive, non-open-world mutation, so the bar is lower. The description still adds real value by disclosing that members inherit the group's space roles immediately and that admin/owner privileges are required, though it doesn't mention reversibility or partial-failure 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?

Three short sentences, zero filler, with the action and identifier forms front-loaded and the precondition last. Every sentence carries distinct information.

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

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

An output schema exists, so return values needn't be explained, and the auth requirement plus role-propagation effect cover the main behavioral questions for a bulk mutation. What's missing is failure semantics when some of the up-to-50 users are invalid or already members.

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 in the schema, including the emails-or-user-ids forms. The description repeats that without adding syntax, format, or edge-case detail, 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?

States a specific verb and resource ('Add people ... to a group') with the accepted identifier forms, so the agent can tell it apart from add_space_members and list_group_members. It doesn't explicitly name those siblings, which keeps it from 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?

'Needs a workspace admin or owner' gives a concrete precondition for calling the tool, which is more than most definitions offer. It stops short of stating when to prefer this over add_space_members or invite_people, so no explicit alternatives or exclusions.

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

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

With annotations already declaring readOnlyHint=false and destructiveHint=false, the description adds real value: it discloses that nonexistent labels get created (an implicit mutation beyond the page) and that 'the page body is not changed', scoping the blast radius. It stops short of noting permission requirements or the 25-label cap 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?

Three short clauses with zero waste: action, side effect, scope guarantee, and prerequisite. Front-loaded with the action and side effect before the version note.

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 mutation with an output schema and annotations, the description covers action, side effect, and scope. Only minor gaps remain (permission needs, duplicate-label handling), so it is nearly complete but not exhaustive.

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 page and labels are fully documented in the schema, including format and lowercase storage. The description adds only the label-creation semantic, not parameter syntax, 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?

States a specific verb and resource ('Add labels to a page') plus a notable side effect (missing labels are created). It is clearly distinct from siblings like remove_label and list_labels, though it never names 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?

The version prerequisite ('Needs Docmost 0.90 or newer') is genuine usage context, but there is no explicit when-to-use / when-not guidance or reference to the alternative label tools (remove_label, list_labels, find_pages_by_label). Usage 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=false and destructiveHint=false; the description adds genuinely new context by stating the operation is additive-only (existing roles are preserved) and requires space admin rights. It does not explain behavior on invalid emails/ids or partial batch failures, which would be the remaining gap for a mutation tool.

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

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

Three tight sentences, zero filler, with the core action first, the identity-format note second, and the disambiguation plus prerequisite last. Every clause carries information an agent needs.

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

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

An output schema exists so return values need no explanation, and auth requirements, idempotency semantics and the sibling alternative are all covered. Only batch-size behavior and failure handling are unaddressed, which keeps it just below fully complete.

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 are already documented upstream. The description restates the user/group identifier formats (email or id, name or id) that the schema already carries, adding no syntax or constraint detail beyond it — baseline 3 applies.

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

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

States a specific verb+resource+effect: 'Give users and groups a role in a space.' It also names the sibling it must not be confused with (change_space_member_role), so an agent can discriminate it from the adjacent role-mutation tool without reading any schema.

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

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

Gives a clear when-not ('People who already have a role keep it') plus the explicit alternative ('use change_space_member_role for them') and the prerequisite ('Needs admin rights in the space'). It stops short of covering edge conditions such as what happens on partial failure or the 25-item batch limit, so it is strong but not exhaustive.

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 this is a non-read-only, non-destructive, closed-world mutation. The description adds real behavioral context beyond them: the admin-rights requirement and the invariant that Docmost keeps at least one admin per space, which tells the agent a demotion can fail.

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, no filler: what it does, the invariant, the permission requirement — in that order.

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?

Output schema exists, so return values need not be described. The description covers scope, prerequisites, and a failure-relevant constraint; only an explicit note on which sibling adds members versus which reassigns roles 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 baseline is 3; the description adds the important semantic that user and group are alternatives ('one user ... or one group'), clarifying the anyOf parameters that the schema documents only individually.

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 (change) and resource (role of a member in a space) and scopes it to one user or one group. The phrase 'in a space' implicitly separates it from change_workspace_role, and 'role' separates it from add_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?

Gives the key precondition ('Needs admin rights in the space') and the targeting rule (one user or one group, not both). It does not explicitly point to change_workspace_role or add_space_members as alternatives, but the guidance is actionable.

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

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

Beyond the destructiveHint/readOnlyHint annotations it discloses the authorization model ('Only an owner can make or change owners') and a real system invariant ('Docmost keeps at least one owner') that an agent must know before attempting a demotion. It does not mention notification side effects or whether a failed demotion produces an error versus a silent no-op.

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

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

Three short sentences, front-loaded with the action and roles, then permissions, then the invariant. Every sentence carries information; only the role semantics sentence is slightly dense.

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?

An output schema exists so return values need no explanation, and the description covers authorization, the role hierarchy, and the one-owner invariant. The main omission is any contrast with the similarly named space-level sibling, which is the most likely source of a mis-call.

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

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

Schema description coverage is 100% and the enum already lists the three roles, so the schema carries the parameter documentation. The description adds light semantics (admin manages people and spaces; owners also manage the workspace and other owners), but the 'user' parameter is never discussed beyond what the schema says.

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

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

States a specific verb and resource ('Change a person's workspace role') and enumerates the exact values. It does not explicitly distinguish itself from the sibling change_space_member_role, so an agent must infer that 'workspace' scope differs from 'space' scope from the tool name alone.

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

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

It gives a precondition ('Needs a workspace admin or owner'), which implies when the call will succeed, but never says when to prefer it over change_space_member_role or invite_people, nor any explicit exclusion. Usage is inferable rather than stated.

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

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

Beyond the readOnlyHint, it discloses performance cost ('takes a while on large spaces') and an important truncation rule: lists cap at 50 entries while the summary counts all. Those are non-obvious behaviors an agent needs to interpret results correctly.

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 dense sentences: the first enumerates what is checked, the second discloses cost and truncation semantics. There is no filler and the important scoping/cost information is not buried.

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

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

Given that an output schema exists, the description does not need to explain return shapes. It covers the check inventory, read cost, and result truncation, which is enough for an agent to decide when and how to call it.

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

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

Schema coverage is 100%, so space_id, max_pages, and stale_days are already documented in the schema. The description reinforces that max_pages bounds full-space reading and stale_days defines staleness, but adds little beyond the schema text.

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

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

It states a specific verb and resource ('health check of one space') and enumerates exactly what is checked: stale pages, empty/untitled pages, duplicate titles, broken links/mentions, and top updaters. That set of checks is distinct from siblings like get_space or list_pages.

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

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

It makes the use case clear (auditing a space's content health) and warns that it reads every page up to max_pages and is slow on large spaces. It does not explicitly name alternatives or exclusions, but there is no sibling that performs a comparable audit.

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 non-destructive, non-open-world write behavior, and the description adds the meaningful precondition of workspace admin/owner rights plus the note that groups gain roles later. It omits failure behavior for unrecognized emails/user ids, which for a bulk-membership creation call would be useful.

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

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

Three short sentences, front-loaded with the action and its optional scope, then permissions. Nothing is redundant or padded.

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

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

An output schema exists so return values need not be explained, and auth plus follow-up path are covered. Only edge-case behavior (invalid member identifiers, partial creation) is unaddressed.

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 all three parameters are documented inline, so the baseline is 3. The description's 'emails or user ids' phrasing duplicates the schema's own wording for `users` rather than adding new semantics.

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

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

States a specific verb+resource ('Create a group') and adds the scope detail that the first members can be supplied at creation, which is exactly what distinguishes it from create-then-add_group_members flows.

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 the required authorization level ('Docmost workspace admin or owner') and forward-references add_space_members for the follow-up role step, so the agent knows the sequencing. It does not explicitly contrast with add_group_members or update_group, so it stops short of full alternative 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 declare readOnly=false and destructive=false, so the description correctly doesn't restate safety. It does add the crucial non-obvious trait that every call produces a new page (retries duplicate), plus what comes back (id and link). It omits permission/auth requirements, which keeps it from a 5.

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

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

Three short sentences, front-loaded with what is created, followed by the return value and then the retry warning. Nothing is redundant and every sentence carries distinct information.

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

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

An output schema exists so return values need no elaboration, annotations cover the safety profile, and all four parameters are documented. For a 4-param create tool, the description supplies the only thing structured fields can't: the non-idempotency warning and the routing to update_page.

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 each parameter is already documented, including content as Markdown and parent_page_id for nesting. The description's "optionally under a parent page and with a Markdown body" merely paraphrases the schema, adding no format or constraint detail beyond it, so baseline 3 applies.

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

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

States a specific verb and resource ("Create a page in a space") plus the optional nesting and body format. It also names update_page as the sibling for the adjacent operation, so an agent can separate create from modify without opening 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?

Gives an explicit when-not-to-use rule ("do not repeat it to retry") and names the correct alternative for editing an existing page (update_page). That is the exact failure mode an agent hits with non-idempotent create tools.

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

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

Annotations already state this is a non-read-only, non-destructive, closed-world operation. The description adds two things annotations cannot: the privilege requirement and the resulting admin membership. 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?

Two compact clauses with zero filler; the effect and the precondition are both front-loaded. 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 a full output schema, complete parameter docs, and clear safety annotations, the description covers the remaining gaps: authorization and the caller's resulting role. Only minor detail like uniqueness of slug is left to inference.

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?

All three parameters are fully documented in the schema, including slug format constraints and defaults. The description adds no parameter detail, which is acceptable given 100% schema coverage but earns only the baseline.

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

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

Specific verb 'Create' plus resource 'space', and it discloses the immediate side effect that the caller becomes admin. It does not explicitly contrast with update_space or list_spaces, but the create-vs-update distinction is unambiguous.

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

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

Gives the concrete precondition that the caller must be a Docmost workspace admin or owner, which is the main gate on use. It does not spell out when to prefer other tools, but no real alternative exists for creating a 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?

Beyond the annotations, the description discloses the 60-minute link lifetime, 50 MB total upload limit, deletion of files not added in time, public access for anyone with the link, and the need to verify via get_upload_status. These are important behavioral traits that materially affect safe use.

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 purpose and key constraints are front-loaded, and most sentences carry useful information. The workflow sentence is somewhat long and could be tightened, but the description remains appropriately scoped for a tool with security, expiry, and size constraints.

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?

An output schema exists, so return values need not be explained in detail. The description still covers the essential call context: intended recipient workflow, token-free upload path, link expiry, size cap, access model, alternative curl path, and status-check follow-up.

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 page, after_text, and after_heading are already documented in the input schema. The description adds workflow context but does not add parameter-specific syntax or placement semantics beyond what the schema provides.

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

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

The description states a specific verb and resource: making a link for adding files to a page. It also explicitly contrasts this with upload_attachment and get_upload_status, so an agent can distinguish it from siblings without inspecting 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?

It explains when to use this tool: to let another person upload files via a browser link, and notes that this avoids token costs. It also names the alternative path (curl with network access instead of upload_attachment) and says to check results with get_upload_status.

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 destructiveHint=true, but the description goes further by disclosing the exact blast radius (sessions revoked, sign-in blocked) and — crucially — what is *not* destroyed (account, pages, roles persist). It also surfaces a self-targeting restriction and an authorization requirement that no annotation conveys.

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

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

Two sentences, front-loaded with the state change and its scope, then the gating conditions. No filler, no restating of the title.

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

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

An output schema exists, so return values need not be described. For a destructive, permission-gated, reversible-by-sibling mutation with one well-documented parameter, the description covers consequences, reversibility, audience, and auth — nothing an agent needs is missing.

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

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

Schema description coverage is 100% and the single 'user' property already documents 'email or user id'. The description only says 'a person' and adds no format, resolution, or ambiguity guidance 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?

States a specific verb+resource ('Deactivate a person') and immediately defines the resulting state: signed out everywhere, cannot sign in. It also names the sibling inverse (activate_member), so an agent can distinguish deactivate from activate or change_workspace_role without opening a schema.

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

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

Gives explicit trigger ('Use it when someone leaves'), an explicit constraint ('You cannot deactivate yourself'), and an explicit prerequisite ('Needs a workspace admin or owner'), plus the escape hatch via activate_member. This is when-to-use, when-not, and how-to-reverse in two sentences.

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 openWorldHint=false, so safety is covered. The description adds useful behavioral detail beyond the schema: it returns a unified diff and defaults to comparing from_version with the current body. It omits edge cases (e.g., missing versions, large diffs) but is solid given the annotation coverage.

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, zero waste, with the core purpose front-loaded and the default behavior appended. Every sentence earns its place.

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

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

With an output schema present, return-value explanation is unnecessary, and readOnly/openWorld annotations cover the safety profile. The description supplies the endpoint semantics and default behavior needed 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 schema already documents all three parameters with identical wording. The only addition is the default-behavior note ('by default from_version is compared with the current body'), which is minor. Baseline 3 is appropriate when the schema carries the parameter semantics.

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

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

The description gives a specific verb and resource: it shows what changed in a page between two points as a unified diff, which is clearly distinct from siblings like get_page_version or list_page_history. It does not explicitly state which sibling it replaces, but the 'unified diff' framing alone distinguishes it.

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 explains the accepted inputs for both endpoints ('current', a version from list_page_history, or a snapshot from list_snapshots) and states the default comparison behavior. It doesn't give explicit when-not-to-use guidance or name alternative tools for related tasks, but the context is clear enough to select it confidently.

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 discloses exactly what is copied (children, attachments, labels), what is not (comments, history), the resulting title ('Copy of ...' vs. unchanged), and placement semantics. It also notes that clients may prompt the user first, which is valuable non-obvious behavior for a write tool with destructiveHint=false.

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

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

Two tight sentences, front-loaded with the core action and its contents, followed by conditional behavior. Dense but every clause carries information; only the client-prompt aside is arguably secondary.

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

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

With an output schema present and annotations covering the safety profile, the description fills the remaining gaps: copy scope, exclusions, naming and destination behavior. An agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description still adds real meaning: target_space_id changes both the destination (top level of that space) and the title convention, which the terse schema text ('Copy into this space instead of the same one') does not convey.

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 precise verb and resource ('Copy a page') and immediately scopes what is included: child pages, attachments and labels. This clearly separates it from siblings such as create_page, move_page or export_page.

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

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

It gives a clear decision rule: omit target_space_id to copy beside the original, supply it to place the copy at the top level of another space. It does not name competing siblings (e.g. move_page_to_space, create_page) or say when duplication is preferable to those, so it stops short of a full 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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it explains the two possible result shapes (inline single page vs. a zip download link), the conditions that trigger the zip (children, attachments, page too long), and the 10-minute link expiry. That expiry and the auto-fallback are exactly the behavioral facts an agent cannot get from structured fields.

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

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

Three short sentences, front-loaded with what the tool does before the result-shape caveat and the sibling routing. 'As Docmost does' is a slightly odd aside but it usefully signals native-format parity, so nothing is wasted.

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?

Output schema exists, yet the description still adds the crucial distinction between inline return and a time-limited zip link, plus the decision rule versus get_page. For a read-only, 4-parameter export tool with full schema coverage, nothing an agent needs 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 earns an extra point by explaining the consequence of include_children/include_attachments (the result becomes a zip link) and of format (Markdown or HTML), which the terse schema descriptions do not convey. It stops short of giving the page-id format details, but the schema already covers that.

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

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

States a specific verb+resource ('Export a page') plus the output formats (Markdown or HTML), and explicitly contrasts itself with get_page. An agent can distinguish it from the read-oriented siblings without opening the schema.

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

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

Gives an explicit when-not ('To read a page, use get_page') and an explicit when ('export when the person wants a file'), naming the alternative tool and the intent that selects it. Only gap is that export_space is not mentioned, but the page/space split is obvious from the 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?

Goes well beyond the annotations: it discloses the admin-rights requirement, that the return value is a download link expiring in 10 minutes, and the non-obvious lazy-build semantics (Docmost generates the zip only when the link is opened). That lazy-build detail is exactly the kind of hidden behavior an agent would otherwise misjudge as an immediate file.

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

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

Three tight sentences with the action first, then the permission gate, then the return-value caveat. Nothing is repeated and nothing is padding.

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?

An output schema exists, so return values needn't be spelled out; the description still supplies the critical operational details — auth requirement, link lifetime, and deferred build. For a 3-parameter export tool this is fully 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 100% and every parameter is already documented, so the schema does the heavy lifting. The description corroborates format enumeration and the attachments flag ('optionally with its files') but adds no format defaults, size limits, or interaction details 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?

States a specific verb and resource ('Export a whole space'), plus the output artifact (zip of Markdown or HTML) and optional attachment inclusion. The scope word 'whole space' implicitly separates it from the sibling export_page, which handles a single page.

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

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

Gives a concrete precondition — 'Needs admin rights in the space' — which tells the agent when the call will fail. It stops short of explicitly naming export_page as the alternative for single-page exports, so routing between the two is still partly inferential.

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 openWorldHint=false, so the safety profile is covered. The description adds a version-gating requirement (Docmost 0.90+) that is not in any structured field, which is genuine extra context; it stops short of describing result ordering or pagination 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?

Two short sentences, the core listing behavior front-loaded and the version prerequisite trailing where it belongs. No 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?

With an output schema present, full parameter documentation, and read-only annotations, the description covers what the agent needs to call it. The version prerequisite is a useful addition; only minor gaps around result scoping remain.

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 label, limit, cursor, and space_id are all fully documented upstream, making 3 the baseline. The description's 'in all spaces or in one' loosely reinforces space_id semantics but adds no syntax or formatting detail beyond the schema.

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

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

States a specific verb and resource: 'List the pages that carry a label,' with the scope qualifier 'in all spaces or in one.' An agent can distinguish this from list_pages and list_labels, though the description never names those siblings explicitly to sharpen the boundary.

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?

'Needs Docmost 0.90 or newer' gives a real prerequisite, and 'in all spaces or in one' implies the space_id filtering choice. However, it never says when to prefer this over list_pages, search, or list_labels, so alternative selection is left to inference.

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

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

The annotations already establish read-only and closed-world behavior, and the description adds important operational details: the download link expires after 10 minutes and a small text file up to 256 KB is included. These are useful behavioral facts beyond the annotations, though authentication or failure behavior is not covered.

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

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

The description is two short sentences, front-loads the returned details, and immediately follows with the time-limited download link. There is no wasted text.

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

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

For a simple single-parameter read tool with a fully documented schema, annotations, and an output schema, the description supplies the key runtime behavior an agent needs: the temporary download link and small text file return. 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% and the sole parameter is documented in the schema as an attachment id sourced from list_attachments or a page body. The description adds no additional parameter semantics, 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 clearly identifies the resource as an attachment uploaded to a page and states that it returns details plus a download link. It does not explicitly distinguish this tool from siblings such as list_attachments or create_upload_link, 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 mention of a download link and returned text file implies the tool is used when an agent needs attachment details or temporary download access. However, it gives no explicit when-to-use guidance, exclusions, or comparison to alternatives like list_attachments.

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 a safe read (readOnlyHint=true, openWorldHint=false), and the description adds real behavioral context beyond them: markdown bodies may be truncated with a `truncated` signal, JSON bodies are never truncated, and oversized pages are refused in JSON mode. These are exactly the non-obvious failure modes an agent needs.

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

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

Three short sentences, front-loaded with what the tool returns, then the format branch and its truncation caveat. No filler; every clause carries information an agent would otherwise have to discover by calling.

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?

Output schema exists, so return-value documentation is not required, yet the description still flags the meaningful field (`truncated`) and the JSON refusal case. For a 2-parameter read tool, 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 earns more by explaining the consequence of `format`: ProseMirror JSON with full formatting and no truncation, intended for replace_page_json. It adds the why, not just the what, though the `page` identifier forms are largely restated from 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?

States a specific verb and resource plus scope: 'Read one page: its title, location and body as Markdown.' An agent knows exactly what comes back. It does not explicitly distinguish itself from close siblings like get_section, get_page_outline or get_page_version, which keeps it at 4 rather than 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?

Gives a clear conditional routing rule: use format='json' when the body will be fed to replace_page_json, otherwise markdown. It does not say when to prefer this over get_section/get_page_outline for partial reads, so no explicit alternatives/exclusions for the tool itself.

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 openWorldHint=false, so the description only needs to add cost/behavior context, which it does by emphasizing 'without the body' (cheap scan) and explaining that section 0 is the pre-heading text. It does not say whether the outline is truncated or paginated for very long pages, which is the remaining behavioral 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?

Three short sentences, front-loaded with what is returned, followed by the decision guidance and one indexing caveat. No filler or redundant restatement of the title.

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

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

An output schema exists, so return values need not be explained, and the description still supplies the key indexing hint about section 0. Only the pagination/truncation behavior for very large outlines is unaddressed.

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?

There is only one parameter and its schema description already covers all accepted forms (page id, slug id, Docmost URL) at 100% coverage. The description adds nothing about the page argument beyond what the schema states, 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?

States a specific verb and resource ('headings of a page') plus what is excluded ('without the body') and the per-heading fields (level and size). It is clearly separable from get_section, which returns body content, and from get_page, which returns the whole page.

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

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

Explicitly names the workflow: use this to locate a section of a long page, then get_section to read it and replace_section to change it. Both the trigger condition ('long page') and the follow-on alternatives are given, leaving nothing to inference.

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

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

Annotations already cover safety (readOnlyHint, closed-world), so the description's real contribution is truncation behavior: the walk stops at max_depth/max_pages, unread children are reported in not_expanded, and re-calling with that page as root_page_id resumes. That is exactly the non-obvious behavior an agent needs.

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

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

Two sentences, no waste, and the scope statement is front-loaded ahead of the truncation/resume mechanics. Every clause carries actionable information.

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

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

With an output schema present, the description needn't enumerate return fields, and pointing at not_expanded ties the traversal semantics to the response. It stops short of noting ordering or what the root-level entries represent, but nothing required to call it correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds semantics the schema lacks: which parameter pair causes truncation and how root_page_id acts as a continuation cursor into the not_expanded set rather than just 'start here'.

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

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

States a specific verb+resource: 'The page tree of a space, or of one page, several levels deep in one call.' That distinguishes it from flat listing siblings like list_pages and from single-page readers like get_page, though it doesn't name a sibling explicitly.

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

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

Usage is implied by the description (use it when you need a multi-level subtree in one call, or to continue from a truncated page), but no alternative is named and no when-not-to-use guidance is given relative to list_pages or get_page_outline.

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 openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: content is Markdown converted by this server, telling the agent not to expect raw storage fidelity. It stops short of saying whether conversion is lossy, which keeps it from a 5.

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

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

One sentence, front-loaded with the action and resource, with the source and output format packed into the same clause. No filler or repetition.

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

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

A read-only, single-parameter tool with an output schema, so return values need no explanation; annotations cover the safety profile. The description supplies the two non-obvious facts (version_id source, Markdown conversion), making it complete enough to invoke 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 coverage is 100% and the single parameter already documents 'Version id from list_page_history', which the description largely restates. No additional syntax, format, or edge-case meaning is added, 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?

States a specific verb ('Read'), a specific resource ('one saved version of a page'), its provenance ('from list_page_history'), and the return format ('as Markdown'). An agent can distinguish it from list_page_history, diff_page, and restore_page_version without opening any 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?

Implicitly tells the agent that the required version_id comes from list_page_history, which is a strong usage pointer, and the Markdown note signals it is a content-reading tool rather than a diff or restore. It does not explicitly rule out alternatives like get_page, but the version-scoped framing makes selection 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 openWorldHint=false, so safety is covered; the description adds the return format (Markdown) and the downstream handoff (section_hash for replace_section), which is genuinely useful chain context beyond structured fields. It doesn't cover failure modes such as an out-of-range index.

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, zero padding. The core operation and its boundary semantics come first, with the return-format and replace_section handoff 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 an output schema present, the description needn't enumerate return fields, yet it names the one value that matters downstream (section_hash) and the serialization (Markdown). Only edge-case behavior (invalid index, empty sections) is unaddressed.

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

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

Schema coverage is 100%, so baseline is 3; the description earns extra credit by defining what a 'section' is at the heading level, which explains how the index parameter should be interpreted. The page parameter's accepted id/URL forms are left to 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?

States a specific verb (read) and resource (one section of a page) plus the exact boundary rule — heading plus everything until the next same-or-higher heading, subsections included. This clearly distinguishes it from siblings like get_page (whole page) and get_page_outline (structure only).

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

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

Explicitly links to the workflow: it returns section_hash for replace_section, and the schema ties index to get_page_outline. It doesn't state when to prefer get_page over this tool, but the context is clear enough to select correctly.

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 openWorldHint=false, so the safe-read profile is covered. The description adds which fields are returned, but that information is also available from the output schema, so it contributes limited additional behavioral context (no error behavior, no permission notes).

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 compact sentence that front-loads the resource and lists the returned fields with zero filler. Nothing could be trimmed without losing information.

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

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

For a one-parameter read tool with full schema coverage, an output schema, and safety annotations, the description is essentially sufficient. Only minor details, such as behavior for an invalid or inaccessible space id, are absent.

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

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

There is a single parameter with 100% schema description coverage ('Space id from list_spaces'), so the schema already carries the semantics. The description adds nothing about the id's format or source, making the baseline 3 appropriate.

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

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

States a specific resource and scope ('Details of one space') and enumerates the fields it returns, which separates it from list_spaces and update_space by implication. It doesn't explicitly name a sibling, so it falls 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?

Usage is only implied: fetch a single space's details. There's no explicit when-to-use, no mention of when to prefer list_spaces or list_space_members instead, and no stated prerequisites. The only routing cue ('Space id from list_spaces') lives in the schema, not the description.

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 openWorldHint=false, so the safety profile is covered. The description adds lifecycle context about files sent and post-Done page inclusion, but does not discuss error behavior, expired upload links, or other operational details.

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 definition is a single, front-loaded sentence with no redundant or filler content. It communicates the core result immediately.

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

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

With an output schema present, the description does not need to enumerate return fields, and the read-only annotation covers the safety profile. It is nearly complete for a simple status tool, though it could clarify when in the upload lifecycle it should be called.

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 upload_id is documented as coming from create_upload_link. The description adds no further parameter meaning, so the baseline 3 is appropriate when the schema already carries the parameter semantics.

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

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

The description clearly identifies the resource as an upload link and states that it reports files sent so far and whether they were added after Done was pressed. It is specific enough to distinguish this status lookup from create_upload_link and upload_attachment, though it does not explicitly name those 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 phrase 'once Done was pressed' implies this is used after an upload flow has progressed, giving some contextual usage signal. However, there is no explicit guidance on when to call it versus create_upload_link or upload_attachment, nor any 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?

Adds substantial behavior beyond the annotations: Docmost emails each invitee a join link and password setup, assigns the workspace role and groups, skips emails already in the workspace or already invited, and lists those skipped. It also discloses the admin/owner requirement, which is important context for a non-readOnly, openWorld invitation 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?

The description is front-loaded with the core action and then layers in useful behavioral details without excessive length. Each sentence mostly earns its place, though the caution sentence is slightly advisory rather than strictly necessary.

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

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

For an invitation tool with annotations covering safety traits and a full output schema, the description is complete: it covers the email mechanism, role/group assignment, duplicate skipping, prerequisites, and a practical caution. An agent has enough context 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 100%, so the schema already documents emails, role, and groups. The description restates that role is member or admin and groups accept names or ids, adding little meaning beyond the structured parameter definitions.

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

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

States a specific verb and resource: inviting people to the workspace by email. The action is clear, but it does not explicitly differentiate itself from sibling invitation tools such as resend_invitation or revoke_invitation, leaving an agent to infer the boundary.

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

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

Provides clear context for use, including the prerequisite that the caller needs workspace admin or owner permissions, and advises checking addresses first. It does not name alternatives or explicitly state when not to use this tool, so it falls short of full when/when-not 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 openWorldHint=false, so the safety profile is covered. The description adds the version requirement, which is genuine behavioral context (the tool may fail on older servers), but says nothing about result ordering, pagination behavior, or empty results.

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

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

A single, front-loaded sentence with zero waste; the resource and scope come first and the version caveat is appended compactly. For a simple paginated list tool this is the right size.

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

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

With an output schema present and full parameter documentation, the description needn't explain return values. It is still thin on how to iterate pages and how this relates to get_attachment/upload_attachment, leaving an agent to infer the listing workflow.

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

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

Schema description coverage is 100% – page accepts id/slug/URL, limit is bounded 1-100 with default 50, and cursor is explained as next_cursor from a prior call. The description adds nothing beyond this, so it sits at the baseline rather than exceeding it.

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

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

States a specific verb and resource ("List the files uploaded to a page"), which cleanly separates it from get_attachment (single-file fetch) and upload_attachment. It doesn't explicitly name any sibling, so it falls short of full sibling differentiation.

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 parenthetical "(Docmost 0.96 or newer)" is a useful prerequisite/version gate, implying when the tool is available. However, it gives no explicit guidance on when to use this versus get_attachment, or on how to page through results with limit/cursor beyond what the schema states.

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 safety (readOnlyHint true, openWorldHint false), so the description is only required to add operational context beyond that. It does so with the version prerequisite 'Needs Docmost 0.90 or newer', which the agent cannot infer from annotations or schema. It says nothing about pagination or result shape, but an output schema covers that.

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

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

Three short sentences, front-loaded with the core resource definition. The first clause restates the direction enum, a slight duplication, but nothing else is wasted.

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

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

With annotations covering safety, a full schema, and an output schema present, the description only needs purpose, trigger, and prerequisites, all of which it supplies. Missing only minor detail such as pagination expectations, which the cursor parameter already implies.

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 page, limit, cursor, and direction, including the enum meanings. The description only restates the direction semantics, adding no extra format or usage detail beyond the schema.

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

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

The description states the exact resource and both directional modes ('Pages that link to this page (incoming), or that this page links to (outgoing)'), so an agent immediately knows what is returned. It does not explicitly name or differentiate itself from any sibling, because no sibling overlaps this 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?

'Use it before moving, renaming or trashing a page' gives a concrete trigger tied to specific sibling tools (move_page, rename_page, trash_page). It gives clear positive guidance but names no exclusions or alternative tools for other backlink-adjacent needs.

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 useful behavioral detail beyond the readOnlyHint annotation: comments are returned oldest first, and replies are represented with parent_comment_id. It does not mention pagination behavior despite limit and cursor parameters.

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 wasted text. The core purpose and ordering behavior are front-loaded.

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

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

With read-only annotations, full schema descriptions, and an output schema, the definition is largely complete. The only notable omission is explicit pagination context for limit and cursor.

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 explains page_id, limit, and cursor. The description adds only the phrase 'on a page' and does not enrich parameter meaning beyond that baseline.

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

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

The description states a specific verb and resource: listing comments on a page. It is clearly different in practice from add_comment and update_comment, but it does not explicitly name or contrast those 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?

Usage is implied by 'List the comments on a page,' but the description gives no explicit when-to-use guidance, exclusions, or alternatives. It is adequate but leaves routing to the agent.

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 openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that: it never mentions that results are paginated via limit/cursor, nor how members are ordered or what identity fields come back.

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 zero waste. It is arguably under-specified rather than verbose, but structurally sound.

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?

An output schema exists, so return values need not be explained, and annotations cover safety. However, for a paginated list tool, the description should at least hint that results are paged and that group ids come from list_groups, leaving the definition barely adequate.

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 limit, cursor, and the group reference (pointing at list_groups) all documented in the schema. The description adds no additional meaning, which is the baseline 3 when the schema does the heavy lifting.

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

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

The description gives a specific verb (list) and resource (people in a group), so its intent is unambiguous. It fails to differentiate from close siblings such as list_space_members, list_workspace_members, or list_groups, which is the only thing keeping it off 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?

There is no guidance on when to use this tool versus its many membership-listing siblings, and no prerequisites are stated. The agent must infer from the name alone that this lists group members rather than space or workspace members.

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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is already covered. The description adds the scoping constraint ('workspace's groups') and optional filtering, but it does not describe pagination behavior or result shape beyond what the schema already provides.

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 wasted words. The core action and optional filter are immediately clear.

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 a complete input schema and an output schema, the definition is nearly sufficient. It could mention pagination or result ordering, but the cursor parameter and output schema cover much of that need.

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 three parameters are already documented in the input schema. The description adds little beyond the schema and slightly narrows the query filter to 'name' even though the schema specifies 'name or email,' so baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('List the workspace's groups') plus an optional filter. It is clear and distinguishes the tool from group membership and group mutation siblings by naming 'groups' as the resource, though it does not explicitly name a sibling 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 phrase 'optionally filtered by a part of their name' implies when the query parameter is useful, but there is no explicit guidance on when to use this tool versus list_group_members, list_workspace_members, or other listing tools. Usage context is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful constraint that only pending invitations are returned (not accepted, revoked, or expired), but says nothing about ordering or result limits. Some added value, not rich context.

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

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

A single front-loaded sentence with no wasted words; the resource scope comes before the optional filter clause.

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

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

With an output schema present and every parameter documented, the description supplies what an agent needs to call the tool correctly. Minor gaps remain around pagination behavior and default ordering, 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, query, and cursor are all documented in the schema, including cursor's next_cursor semantics. The description's mention of the email filter duplicates the schema and adds no format or matching detail beyond it. Baseline 3 applies.

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

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

States a specific verb ('List') and resource ('pending invitations to the workspace') with a clear scope qualifier. This distinguishes it from the other list_* siblings such as list_workspace_members and list_space_members, which cover accepted members rather than invitations. It is clear, though it does not name a sibling explicitly.

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

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

The 'optionally filtered by a part of the email' phrase implies when to pass query, but there is no statement of when to use this tool versus resend_invitation/revoke_invitation or the member lists. Usage is implied rather than 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?

The annotations already establish that this is a read-only, non-open-world operation. The description adds a useful compatibility prerequisite ('Needs Docmost 0.90 or newer'), but does not explain authorization needs, pagination behavior, or other operational details.

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

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

The description is two short sentences, front-loads the scope distinction, and includes the version prerequisite without unnecessary filler. Every sentence contributes useful information.

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

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

For a simple read-only list tool with full schema coverage and an output schema, the description is nearly complete: it explains the page-vs-workspace behavior and compatibility requirement. Minor operational details such as pagination and permissions are left to structured fields.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics for the optional page parameter: omitting it lists all labels used in the workspace. It does not add details for limit or cursor, which remain 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 ('List labels') and clarifies both scopes: labels for one page, or all workspace labels when no page is specified. This distinguishes it from label-mutation siblings and from find_pages_by_label, which performs the reverse lookup.

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 explains the two operating modes through the optional page parameter, but does not explicitly say when to use this tool rather than alternatives such as find_pages_by_label. The usage is implied clearly enough, but there are no stated exclusions or alternatives.

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 openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: result ordering is newest-first and Docmost persists a version a few minutes after edits stop, which tells the agent a just-made edit may not yet appear. It does not discuss pagination limits, but the schema does.

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 earning its place: what it returns, the write-latency caveat, and the hand-off to sibling tools. Ordering and author information are front-loaded.

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

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

With an output schema present, the description needn't explain return shape, and it covers scope, ordering, latency semantics, and alternatives. Only the pagination story (cursor) is left entirely to the schema, a minor 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 description coverage is 100%, so the schema already explains page id/slug/URL, limit, and cursor semantics. The description adds no parameter-level syntax or format detail beyond that, making the baseline 3 correct.

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

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

States a specific verb and resource ('List the versions of a page') plus the ordering ('newest first') and the payload detail ('with who changed it'). This clearly separates it from get_page_version, list_snapshots, and the other page-related 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?

Explicitly routes the agent onward: 'Read one with get_page_version or compare with diff_page,' which distinguishes enumeration from retrieval and diffing. It lacks any explicit 'when not to use' (e.g., list_snapshots vs. version history), 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 openWorldHint=false, so safety is covered. The description adds traversal semantics that annotations cannot convey: one-level-at-a-time pagination and the meaning of has_children as a signal for the next call. It doesn't restate cursor/limit behavior, but the schema already documents those.

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

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

Three sentences, front-loaded with the core behavior, then the branching rule, then alternative routing. No redundant restatement of names or schema fields.

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?

Output schema exists so return values need not be explained, yet the description still clarifies the one output field an agent must act on (has_children). Combined with mode semantics and sibling routing, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description still adds value by defining what the ABSENCE of parent_page_id means (top-level pages), a default-behavior detail the schema's per-parameter text does not state.

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

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

States a specific verb and resource (list pages of a space as a tree, one level at a time) and immediately defines the two operating modes via parent_page_id. This clearly separates it from flat-listing or tree-fetching 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?

Explicitly says when to use this versus alternatives: get_page_tree for multiple levels in one call, suggest or search for finding a page by name. Both the exclusion and the routing target are named.

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 openWorldHint=false, so the safety profile is covered. The description adds genuinely non-derivable behavior: newest-first ordering, the fact that only snapshots created by this server prior to the agent's own edits are listed, and a 30-day retention window that tells the agent results may be incomplete for older content.

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 the core verb+resource+ordering front-loaded and the retention caveat placed last. No filler or restatement of the title.

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

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

An output schema exists, so return values need not be explained, and the description covers ordering, retention, and scope. The one remaining gap for a snapshot/versioning surface is routing relative to list_page_history, get_page_version, diff_page, and restore_snapshot.

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

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

Schema description coverage is 100% — the 'page' parameter already documents accepted forms (id, slug id, URL) and 'limit' documents its default and bounds. The description adds no parameter-level detail beyond what the schema carries, 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?

States a specific verb and resource ('List the snapshots of a page body') plus scope ('that this server saved before your own changes to it') and ordering ('newest first'). An agent can identify what it returns, though the description never distinguishes it from close siblings like list_page_history or get_page_version.

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

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

Usage is only implied: the 'saved before your own changes' framing hints at pre-edit recovery scenarios, and a sibling named restore_snapshot suggests the workflow. There is no explicit 'use this when X, use list_page_history when Y' guidance or statement of 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact—results include both users and groups with roles—but says nothing about pagination behavior, whether inherited/effective roles are included, or what role information is returned.

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

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

A single front-loaded sentence with zero waste. It is efficient, though the terseness comes at the cost of the missing usage and behavioral detail noted above.

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, the key elements are covered elsewhere: annotations give the safety profile, the schema fully documents all three parameters, and an output schema exists to explain return values. Only the user-vs-group/role semantics and pagination expectation are left thin.

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 space_id, limit, and cursor are all documented in the schema (space_id even points to list_spaces). The description adds no additional parameter meaning, 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?

Specific verb ('List') plus resource ('users and groups that have a role in a space') and the 'in a space' scoping implicitly separates it from list_workspace_members. It does not explicitly name or contrast with 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?

Usage is only implied: an agent can infer this is the per-space membership listing as opposed to the workspace-level one, but no when-to-use, prerequisites, or named alternative (list_workspace_members, list_group_members) 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds two genuinely useful facts beyond them – results are limited to spaces the caller can access, and each entry carries the caller's role – but says nothing about ordering, clustering, or handling empty results, so it is incremental rather than rich.

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, zero filler, with the resource and scope front-loaded and the workflow cue second. Nothing repeated from schema or annotations.

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?

Output schema exists and annotations cover safety, so the description only needs to orient the agent – which it does by naming the access scope and the returned role field. A note on ordering or on what an empty list implies would close the remaining gap.

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

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

Schema description coverage is 100% and both parameters (limit, cursor) are fully documented in the schema with defaults and bounds. The description adds no syntax or format detail about them, so baseline 3 applies.

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

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

States a specific verb (List) and resource (Docmost spaces) plus a scope qualifier ('you can access') and the extra payload ('with your role in each'). That distinguishes it from get_space (single space) and create_space without naming them explicitly; only the absence of explicit sibling naming keeps it from 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?

'Start here to get the space ids other tools need' gives a concrete sequencing cue that tells an agent to call this before tools requiring a space id. It doesn't state exclusions (e.g., when to prefer whoami or get_space instead), 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 openWorldHint=false, so safety is covered. The description does add one genuine behavioral fact — results are ordered most recently deleted first — which is not in the schema or annotations. It says nothing about pagination depth or whether the space must be accessible, so the addition is modest.

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 well-formed sentence with the resource and the ordering front-loaded. Nothing is wasted and nothing needs to be scanned for.

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

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

With an output schema present and full parameter documentation, the remaining burden on the description is small; it supplies the one thing structured data lacked, the sort order. Only the relationship to restore_page / list_pages is unstated.

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 all three parameters (space_id, limit, cursor) are documented inline, including the list_spaces cross-reference. The description adds no parameter meaning beyond that, which is 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?

States a specific verb (List) and resource (pages in the Trash of a space), plus a scope qualifier (a space) that separates it from workspace-wide listing. It is implicitly distinct from list_pages, but that separation is never made explicit by naming the sibling.

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

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

Usage is only implied: an agent infers this is the lookup to run before restore_page or trash_page. No when-to-use/when-not guidance and no named alternative (e.g., list_pages for live pages) is given.

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 openWorldHint=false, so safety is covered. The description adds that each entry carries a workspace role and that filtering matches partial names/emails — useful context — but says nothing about pagination behavior or whether deactivated members are included, both of which matter for this 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 and resource, with the optional filter clause deferred to the end. Nothing is wasted or repeated.

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

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

With an output schema present and full parameter documentation, the description needn't explain return values or pagination mechanics. The main remaining gap is the lack of disambiguation from list_space_members and list_group_members, which is a real risk given eight sibling membership tools.

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, query, and cursor each documented (including next_cursor semantics), so the schema carries the parameter burden. The description only restates the query filter as a substring match, adding marginal clarification over the schema's 'Part of a name or email to filter by.'

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?

Clear verb+resource: lists people in the Docmost workspace, states that workspace role is returned, and that filtering is optional and substring-based. It does not, however, distinguish itself from the nearby sibling list_space_members (per-space members) or list_group_members, which an agent could easily confuse it with.

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

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

Usage is implied by 'workspace' and the optional filter, so an agent can infer this is the workspace-wide roster rather than a space roster. But there is no explicit 'use this when...' statement and no exclusion naming list_space_members as the alternative for space-scoped 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?

Beyond the annotations, the description discloses an important side effect: 'Child pages move with it.' It also explains ordering behavior (end by default, start with first=true, or after after_page_id). It does not cover permissions or failure conditions such as attempting to move a page under its own descendant.

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 tightly written sentences with no filler. It front-loads the scope and destination behavior before adding the child-page side effect.

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 same-space move operation with full schema coverage, annotations, and an output schema, the description covers the key calling context: destination modes, ordering, and child-page movement. Remaining gaps are around error conditions and explicit sibling routing, but no essential invocation detail is missing.

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

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

The schema already documents all four parameters at 100% coverage, but the description adds relational meaning: an empty parent_page_id means top level, first=true places the page at the start, after_page_id places it right after a specific page, and the default destination is the end of the level. It does not explicitly state whether first and after_page_id are mutually exclusive.

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: 'Move a page to another place in the same space.' It immediately clarifies the destination options (parent_page_id or top level) and implicitly distinguishes this from the cross-space sibling move_page_to_space by emphasizing 'same 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 clear context for when to use this tool: moving within the same space, either under a parent or to top level. It also explains how to choose placement using first=true or after_page_id, but it does not explicitly name move_page_to_space as the alternative for cross-space moves.

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