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

With no annotations provided, the description carries the full behavioral disclosure burden, but it only states the action without revealing side effects, return behavior, or validation rules. It does not mention whether the created comment object is returned or how parent_comment_id affects behavior, though some of these are covered by the output schema.

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

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

The description is a single concise sentence with no filler, front-loading the core purpose effectively. It is efficient and easy to parse, though quite terse.

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

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

The schema covers all parameters and an output schema exists, so returns need not be spelled out. However, the description is minimally viable and lacks usage context or behavioral disclosure, leaving an agent with no sense of when to choose this over siblings or what side effects to expect.

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

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

Schema description coverage is 100%, so the parameters are already documented in the input schema. The description adds no parameter-specific meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb ('Adds') and resource ('a comment to a page'), and the action is clearly distinct from sibling tools like update_comment and get_comments. It leaves no ambiguity about what operation is performed.

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

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

No guidance is provided on when to use this tool versus alternatives such as get_comments or update_comment. There are no explicit conditions, prerequisites, or exclusions, so an agent must infer usage from the name and schema alone.

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?

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It reveals the import endpoint mechanism, the fact that title is taken from the first heading unless overridden, and that content is optional. These are non-obvious behaviors an agent must know. It lacks permission or error details, but the core mutation behavior is transparently disclosed.

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

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

The description is concise, with the primary purpose stated in the first sentence and details in a short second paragraph. It is front-loaded with the main action and adds necessary nuance about the import mechanism and title precedence without fluff. This efficient structure makes it easy for an agent to quickly extract the essence.

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

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

Given the 5-parameter tool with only 1 required, the description covers the key behaviors: creation, optional content, title precedence, and the import mechanism. It does not explicitly state what happens when content is null (though default null implies empty page) or mention permissions, but the output schema exists to cover return values. Overall, it provides enough context for an agent to call 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?

The schema already describes all parameters with 100% coverage, so the baseline is 3. The description adds meaning beyond the schema by explaining the interaction between title and content: the title defaults to the first heading of the content unless explicitly provided. This clarifies the title parameter's behavioral semantics and also explains why the format parameter matters, as content is uploaded via import. This added context justifies a score above 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 the exact action: 'Creates a new page in a space, with or without content.' This is a specific verb and resource, and it clearly distinguishes the tool from update/delete siblings by focusing on creation. It also highlights the key feature of optional content, leaving no ambiguity about what the tool does.

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

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

The description does not explicitly name alternatives, but it provides important context: if content is provided, the page is uploaded via the import endpoint, which is the only REST way to persist the page body. This implies usage when content persistence is needed and hints at a constraint. However, it does not say when to avoid this tool or compare it with siblings like update_page, so guidance is implicit rather than explicit.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. 'Creates a new space' only conveys the basic mutation; it says nothing about permissions, uniqueness, slug-generation behavior, or failure semantics.

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

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

The description is a single concise sentence with no filler. It front-loads the action and resource clearly, and every word earns its place.

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

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

The input schema fully documents parameters and an output schema documents the return shape. However, important operational details remain unexplained, such as how slug handles null/default, whether names must be unique, and what permissions are required. For a simple create operation this is mostly adequate but not 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 name, slug, and description are fully documented in the input schema. The tool description adds no parameter-level meaning beyond what the schema already provides, so the baseline 3 applies.

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

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

The description states the exact operation ('Creates') and resource ('a new space'), which is unambiguous. Even with siblings like create_page and create_comment, the resource name 'space' clearly distinguishes this tool.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor does it state any exclusions or prerequisites. The agent must infer usage solely from the resource 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?

With no annotations, the description carries the full burden of behavioral disclosure, and it clearly states the key non-permanent behavior: the page is moved to trash and recoverable. It does not cover side effects such as impacts on child pages or permissions, but the core behavioral trait is transparent.

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

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

The description is a single sentence with no wasted words. The action is front-loaded ('Moves a page to the trash') and the recovery note is placed efficiently in a parenthetical.

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 one-parameter tool with an output schema, the description provides the essential context: what the tool does and that it is reversible. It is missing only peripheral details like permissions or effects on related content, which are minor for correct invocation.

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

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

The schema already provides 100% coverage for `page_id` with the explanation 'UUID or slugId of the page.' The description adds no additional parameter semantics, so the baseline score of 3 applies.

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

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

The description uses a specific verb and resource: 'Moves a page to the trash', which clearly describes what the tool does and distinguishes it from permanent deletion. It also references `restore_page`, reinforcing the contrast with a sibling tool and removing ambiguity about the action's nature.

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

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

The description implies the appropriate use case: deleting a page in a recoverable way, and points to `restore_page` for the reverse operation. However, it does not explicitly state when to choose this tool over other alternatives or mention 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action without mentioning that it is a read-only operation, whether pagination is applied, or any side effects. The schema hints at a limit, but the description does not explain how results are ordered or limited.

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, concise sentence with no filler or redundant phrasing. The key action and resource are stated upfront, and nothing extraneous is included.

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 getter with a complete schema and an output schema present, the description covers the essential purpose. It does not mention pagination or ordering, but the schema's limit parameter and the output schema likely cover those details. The description is adequate for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, covering both page_id and limit. The description adds no additional meaning beyond the schema, but the schema already documents the parameters adequately. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('gets') and a specific resource ('comments of a page'), clearly distinguishing it from sibling tools like get_page, create_comment, or get_page_history. Even without naming alternatives, the purpose is unambiguous.

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

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

The description implies usage for fetching comments on a page, but provides no explicit when-to-use or when-not-to-use guidance. There is no alternative comment-listing sibling, so the absence of exclusions is acceptable, but the tool does not state any context 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It reasonably implies a read-only operation and indicates the data scope (authenticated user and workspace), but it does not mention error behavior, authentication failure handling, or whether workspace information can vary. Important details are missing but the core behavior is clear.

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

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

A single, front-loaded sentence that states exactly what the tool returns. There is no filler, redundancy, or unnecessary context.

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

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

For a zero-parameter tool with an output schema, the description is nearly complete. It identifies the key output categories (user and workspace information) and does not need to describe return values. The only minor gap is the lack of any usage or error context, but the tool's simplicity limits the impact.

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

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

The tool has zero parameters, so the schema already fully covers parameter semantics. The baseline of 4 applies because there is nothing for the description to add about parameters.

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

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

The description states a specific verb ('Returns') and a clear resource ('the authenticated user and workspace information'). It is unambiguous and easily distinguishable from sibling tools such as list_workspace_members or get_workspace_overview, since it targets the current authenticated session.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives, and does not mention any exclusions or prerequisites. Usage is only weakly implied by the name and the phrase 'authenticated user,' so the agent must infer the intended context.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It does well by specifying that the tool returns the full text in a `content` field and that it internally combines `/pages/info` with `/pages/export`. It does not cover auth, errors, or rate limits, but the core read behavior is transparent.

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 short and front-loaded with the main purpose. The second sentence adds a useful detail about the `content` field, and the third provides a helpful implementation note. There is mild overlap between the first two sentences, but overall it is efficient and well-structured.

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

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

For a simple two-parameter read tool with a present output schema and full schema parameter coverage, the description is nearly complete. It explains what the tool returns and how it composes its result; only minor extras like authorization requirements or rate-limit behavior 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?

The input schema already fully describes both parameters: `page_id` as a UUID/slugId and `format` with a default and allowed values. Schema description coverage is 100%, so the description does not need to add parameter detail. It adds no extra parameter 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 action and resource ('Fetches a page') and clearly defines the scope of the result: metadata plus content. It does not explicitly name or contrast sibling tools like get_page_history, but the 'metadata and content' framing makes the tool's purpose unambiguous.

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

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

The intended usage context is clear: call this when you need a page's metadata and full textual content, identified by page_id. No exclusions or alternative tools are mentioned, but the description provides enough context for an agent to select it appropriately for a direct page-content fetch.

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

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

No annotations are provided, so the description is the sole behavioral source. It signals a read-only operation via 'Returns' and names the result type, but it does not disclose ordering, whether the current page is included, or behavior for a root page with no ancestors. These gaps are minor for a simple getter.

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

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

The description is a single front-loaded sentence with no filler. It conveys the essential behavior and result type without unnecessary explanation.

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

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

For a one-parameter read-only tool with an output schema present, the description is largely sufficient. It could mention edge cases like a root page having no ancestors, but the simplicity and available schema mitigate that gap.

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

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

The schema already documents page_id as a required string with 'UUID or slugId of the page,' covering 100% of parameter semantics. The description adds no extra parameter-level detail beyond tying the parameter to the page whose breadcrumbs are returned, which meets 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?

The description uses a specific verb ('Returns') and a specific resource ('ancestor path (breadcrumbs) of a page'), making the tool's purpose immediately clear. It is easily distinguishable from siblings like get_page and list_child_pages, which serve different navigation roles.

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

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

The description implies when to use the tool: whenever a page's breadcrumb/ancestor path is needed. However, it does not explicitly mention alternatives or exclusion conditions, leaving the agent to infer the usage boundary from the sibling list.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It only says 'Lists...', so it does not mention pagination, ordering, whether deleted versions are included, or any side effects. It is clearly a read operation, but behavioral details are otherwise absent.

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

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

The description is a single, focused sentence with no wasted words. It is concise, but it is also very sparse and does not use any structure to highlight key constraints or usage context.

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

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

For a one-parameter tool with an output schema, the description is minimally adequate. However, it omits useful context such as what the version list contains, ordering, or whether it includes the current version, which would help an agent reason about results without inspecting the output schema.

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

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

The schema covers 100% of the single parameter with the description 'UUID or slugId of the page.' The tool description adds no additional parameter semantics, so the baseline score of 3 applies.

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

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

The description states a specific verb ('Lists') and resource ('version history of a page'), making it clear this is a read-oriented history tool rather than a page-content getter. It does not explicitly differentiate from siblings like get_page or restore_page, but the resource is distinct enough.

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

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

There is no explicit guidance about when to use this tool versus alternatives such as get_page or restore_page. The description only implies that this is for version history, leaving the agent to infer the appropriate context.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only says 'gets details,' which implies a read operation, but does not explicitly state that it is non-mutating, whether it requires specific permissions, or what happens if the space_id is invalid. No error behavior or return format is disclosed beyond the schema.

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

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

The description is a single concise sentence with no wasted words. It is appropriately brief for a simple getter tool. However, it is so minimal that it borders on under-specification, lacking any additional context that could be included without becoming verbose.

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

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

For a tool with one parameter and an output schema present, the description is minimally adequate. It communicates the core function, and the output schema covers return values. However, the absence of any usage guidance or behavioral transparency makes it less complete than it could be, especially given the existence of sibling 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?

The input schema provides 100% coverage, describing space_id as 'UUID of the space.' The description adds no additional meaning about the parameter—it only implies the space is identified by ID. Since the schema already documents the parameter adequately, a baseline score of 3 is appropriate; the description does not enhance it.

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

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

The description states 'Gets the details of a space,' which clearly identifies the verb (gets) and resource (space). It implies a single-space retrieval by ID, but does not explicitly contrast with list_spaces, which lists multiple spaces. The purpose is understandable but could benefit from naming the sibling to disambiguate.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of when to prefer get_space over list_spaces or get_page, and no exclusions or prerequisites are stated. The description relies entirely on the agent's inference.

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

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

With no annotations provided, the description carries the full burden, and it delivers: it spells out what each activity level costs, warns that full activity and check_empty cost one request per page, explains that the summary adds no extra cost, and documents the exact per-page fields returned. This gives an agent an accurate mental model of both behavior and performance trade-offs.

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 single most important instruction ("Start here"), and every subsequent sentence adds distinct information: scope, sibling differentiation, output shape, cost model, and summary semantics. It is long only because the tool has meaningful behavioral nuance, with no filler or repetition of 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?

For a complex listing tool with no annotations, the description covers purpose, alternatives, output shape, cost behavior, and even a caveat about date coverage. Since an output schema exists, return-value details do not need to be duplicated, and the description fills the remaining gaps an agent would need to call 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 coverage is 100%, so the baseline is 3, but the description adds genuine value beyond the schema: it connects activity levels to the returned recently_updated and per-page date fields, characterizes max_pages as a safety cap, and explains why check_empty is expensive. This helps an agent choose parameter values rather than just knowing their types.

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 opening line "Start here. Lists everything in the workspace: every space and every page" states a specific verb, a clear resource, and the full scope. It also explicitly contrasts itself with list_child_pages by noting it walks the whole page tree, so an agent can distinguish it from the closest sibling 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?

The description gives concrete use cases: answering 'what do I have?', taking an inventory, and finding a page by title before reading it with get_page. It also names the relevant sibling (list_child_pages) and explains the difference in tree traversal, making the selection condition explicit.

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

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

No annotations are provided, so the description carries full burden. It discloses the depth limitation (direct children) and the alternative to avoid misuse, but does not mention return format, pagination, or potential errors. For a query tool, this is adequate but not 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?

The description is remarkably concise—two sentences plus a note. It front-loads the most critical constraint (direct children only) and immediately follows with the alternative. No wasted words; 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?

The tool is simple, has an output schema, and schema covers all parameters. The description provides clear usage boundaries and routing to a sibling, which is sufficient for an agent to call correctly. Minor gaps like specifying that page_id and space_id are mutually exclusive are not critical due to schema hints.

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 documents all three parameters. The description adds context on how page_id and space_id relate (one is resolved automatically), which goes slightly beyond schema, but it doesn't fully compensate for any ambiguity, e.g., what happens if both are provided.

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

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

The description states a specific verb ('Lists') and resource ('direct children of a space or a page'), and explicitly clarifies scope ('one level, not the whole tree'). It names the sibling alternative for broader enumeration, which distinguishes it from related tools like get_workspace_overview.

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

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

It clearly states what the tool does (direct children only) and points to the alternative for full tree enumeration, but does not explicitly state when not to use it beyond that. The context of 'one level' implicitly guides correct usage.

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

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

Annotations are absent, so the description carries the full burden. It states the core behavior (listing recently updated pages) but adds no detail on ordering, pagination, what 'recently' means, or whether it returns full pages or summaries. It fails to disclose any behavioral traits beyond the literal action.

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

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

A single, clear sentence with no redundancy. It is appropriately front-loaded and efficient, conveying the essential purpose without fluff.

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

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

Given the presence of a complete schema and an output schema, the description is minimally adequate. However, it omits important contextual details such as sort order (by update time descending), handling of the optional space_id (workspace-wide if omitted), and any implicit limits. These are not covered by annotations, leaving some ambiguity for an agent deciding 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 both parameters (limit and space_id) are already documented. The description adds no additional meaning about parameters—it does not explain how limit or space_id affect results beyond what the schema states. Baseline 3 applies.

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

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

The description clearly states a specific action ('Lists') and resource ('pages'), with a qualifier ('recently updated'). It distinguishes from siblings like get_page (single page) and search_pages (search), but does not explicitly name alternatives or contrast them, so it's not a 5.

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

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

No guidance is provided on when to use this tool versus siblings. It does not mention alternatives, exclusions, or contextual cues for selection. The description is purely functional without any usage direction.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states that the tool lists accessible spaces, but does not mention pagination behavior, ordering, whether archived spaces are included, or any access-related edge cases.

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 one short, focused sentence with no filler. It front-loads the action and resource while also conveying the access scope, making it highly efficient.

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

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

Given that this is a simple listing tool with one optional parameter and an output schema, the description is largely sufficient for correct invocation. It lacks usage guidance and some behavioral details, but nothing required to make the call is missing.

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

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

The single parameter 'limit' is fully documented in the schema with a clear meaning and default. The description adds no parameter-specific information, but the schema already provides 100% coverage, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Lists') and resource ('spaces'), and scopes it to 'the user has access to.' This clearly distinguishes it from sibling tools like get_space (single space) and create_space (mutation), so an agent can select it correctly.

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 about when to use this tool versus alternatives, nor any exclusions or mention of related tools like search_pages or get_workspace_overview. The intended context is only implied by 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Lists the members of the workspace' states the core operation but does not disclose any additional traits such as whether the operation is read-only, how pagination works, whether results are ordered, or what the response contains. The output schema covers return shape, but the description itself adds no behavioral context beyond the obvious action.

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

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

The description is a single concise sentence with no filler, repetition, or irrelevant content. It is front-loaded with the verb and resource, making it easy to scan.

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 one-parameter list tool with an output schema, the description is minimally viable, but it lacks usage context and any behavioral details. The agent can infer that it lists workspace members and can limit the count, but there is no guidance about when to choose this over other tools or what additional behavior to expect.

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 there is only one parameter, 'limit', which is already clearly documented as 'Maximum number of members to return.' The description adds no parameter-specific meaning, but because the schema fully covers the parameter semantics, the baseline of 3 applies.

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

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

The description uses a specific verb ('lists') and a clear resource ('members of the workspace'). It is immediately distinguishable from sibling tools like list_spaces, get_current_user, and page-focused tools, so there is no ambiguity about what the tool does.

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

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

The description gives no guidance on when to use this tool versus alternatives, nor does it mention any exclusions, prerequisites, or workspace context. It is implied that this tool is for workspace members, but no explicit routing or comparison to sibling tools 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?

With no annotations, the description carries the full disclosure burden. It discloses the mutating nature, default append behavior, precedence of placement modes, and the internal fractional-indexing mechanism so the agent knows it never needs to construct positions manually. However, it doesn't disclose edge-case behaviors: what happens when multiple placement parameters are passed together, or whether cycle prevention exists when moving a page into 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?

Roughly 120 words, purpose front-loaded in the first sentence, with a scannable bullet list for the three placement modes. The fractional-indexing paragraph earns its place by telling the agent not to hand-construct positions — a genuine failure-mode prevention. No sentence 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?

All parameter usage modes, the default behavior, and their precedence are covered, and an output schema exists so return values need not be described. The remaining gaps are moderate edge cases: behavior under conflicting parameters (e.g., after plus before, or parent_page_id plus a sibling from the old parent) and cycle prevention when nesting a page into its own subtree.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine meaning beyond the schema by mapping parent_page_id to the 'nest' mode, after/before to the 'reorder' mode, clarifying that after/before refer to siblings, and establishing a precedence order among the parameters. It also explains the default behavior of omitting all placement parameters.

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

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

The description opens with a specific verb and resource: 'Moves or reorders a page.' It immediately sets the mechanism ('Say where it should go; the position is computed') and centers on page position, which clearly separates it from siblings like update_page and update_page_content that handle content or properties.

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

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

The description gives explicit context for the three placement modes in order of preference — nest via parent_page_id, reorder via after/before, or default to appending at the end of the current parent. It also justifies using this tool over hand-computing positions by explaining fractional indexing. It doesn't explicitly name sibling tools as alternatives, but the position-focused framing makes the distinction 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It clearly states the action (restore) and the target state (in the trash), but does not disclose side effects, such as whether restoring restores child pages, whether permissions are required, or whether the page ID must be a specific type. The description is accurate but minimal.

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

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

The description is a single sentence with no wasted words. It is front-loaded with the action and resource, making it easy for an agent to parse quickly.

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

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

The tool has a simple input schema (one required parameter) and an output schema, so the description is mostly sufficient. However, with no annotations and no mention of edge cases (e.g., restoring a page that is not in the trash, or restoring a page with children), the description leaves some behavioral gaps. It is adequate but not comprehensive.

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 the single parameter (page_id) as a UUID or slugId. The description does not add additional meaning beyond the schema, but with full coverage, the baseline of 3 is appropriate.

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

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

The description states a specific verb ('restores') and resource ('a page that is in the trash'), clearly distinguishing it from sibling tools like delete_page or move_page. It is concise and unambiguous, 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 description implies the tool is for restoring trashed pages, which gives clear context for when to use it. However, it does not explicitly state when not to use it or mention alternatives, such as using get_page to verify trash status or move_page for non-trash pages.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does a good job by revealing that this is lexical PostgreSQL FTS and that stopwords will cause empty results, which is an important edge case. It could additionally mention result ordering or access restrictions, but the core matching behavior is transparent.

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

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

Two tight sentences with no filler. The main action and search method are front-loaded, and the stopword caveat earns its place as an important behavioral warning.

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

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

The description is sufficient for a simple search tool, especially since an output schema exists and parameter docs are complete. It lacks explicit guidance on sorting/relevance or when to use it instead of retrieval tools, but the combination of description and schema covers the essential behavior.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining that the query parameter expects meaningful, non-stopword terms and warns about zero-result behavior for empty-meaning words.

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

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

The description clearly states the tool's verb and resource: 'Searches pages by keyword (full-text search).' It is specific enough to distinguish from page CRUD tools, though it does not explicitly name or differentiate sibling search/list tools.

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

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

The description gives useful querying guidance: use meaningful words, stopwords return no results. However, it never explicitly says when to prefer this tool over siblings like get_page, list_child_pages, or list_recent_pages; the usage is only implied by 'keyword search.'

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

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

No annotations are provided, so the description carries the full behavioral burden. It makes the mutation intent clear but does not state whether existing content is overwritten, whether permissions are required, whether the operation is reversible, or what happens if the provided content is invalid Tiptap JSON.

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

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

The description is a single, focused sentence with no filler. The action and target are front-loaded, making it easy to parse quickly.

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

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

The schema fully documents both required parameters and an output schema exists, so the tool is invocable for a simple operation. However, the lack of usage context, behavioral caveats, and any differentiation from sibling tools keeps it from being fully self-contained.

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 parameter meanings are already fully documented. The description adds no additional semantic detail beyond the schema, which is the expected baseline given full coverage.

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

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

The description clearly states a specific verb ('Updates') and resource ('content of a comment'). This distinguishes it from sibling tools like create_comment or update_page without needing to inspect 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?

There is no guidance on when to use this tool versus alternatives, no mention of prerequisites such as the comment already existing, and no exclusions or alternative tool suggestions. The agent is left to infer usage from the name and 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?

With no annotations, the description carries the behavioral disclosure burden. It clearly identifies the operation as a rename and scopes out content changes, but it does not mention side effects, permissions, or failure behavior. The output schema likely covers the response, but the description adds only minimal extra behavioral context.

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

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

Two short sentences with no wasted words. The core action is front-loaded, and the explicit alternative routing follows 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?

For a simple rename tool with only two parameters, one required, and an output schema, the definition is complete. It tells the agent what the tool does, what it does not do, and routes to the relevant sibling. No critical information is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well (page_id as UUID/slugId and title as 'New title.'). The description adds no additional parameter-level meaning, which is acceptable at the baseline given complete schema coverage.

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

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

The description states a specific action, 'Renames a page,' with a clear resource and scope. It also explicitly distinguishes itself from update_page_content, which is the sibling likely to be confused with 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 explicitly says when to use this tool (to rename) and when not to (to change content), naming the alternative update_page_content. This leaves little ambiguity for an agent selecting between the two.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that the tool opens a collaboration WebSocket, waits for persistence for ~13 seconds, replaces/appends/prepends content exactly as described, and converts Markdown using Docmost's own converter. It even mentions the required yjs extra, going well beyond the schema.

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

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

The description is front-loaded with the core action, then efficiently explains the mechanism, latency, comparison to the sibling, mode behavior, and dependency. The bullet list for modes is scannable and every sentence adds necessary context; there is 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?

For a complex tool involving WebSocket communication, persistence delay, multiple modes, and a dependency, the description covers everything an agent needs to invoke it correctly: what it does, how it works, why it differs from alternatives, what the modes mean, and the installation requirement. An output schema exists, so return value details are not the description's responsibility.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics by explaining the three mode values in detail and their real behavioral differences, including that 'replace' yields exactly the given Markdown. This goes beyond the schema's terse parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Writes into the body of an already-created page.' It then distinguishes the tool from the sibling update_page by explaining that the REST API cannot perform this operation and that mode genuinely works here. This makes the tool's unique purpose unmistakable.

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

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

The description explicitly contrasts this tool with '/pages/update', noting that the REST API cannot edit page bodies and that the alternative ignores its operation field. It clearly implies that this tool is the correct choice when the body content itself needs to be changed, while naming the sibling it is not.

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