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

The annotations declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, yet the description explicitly advertises destructive, non-idempotent operations such as documents.delete, documents.create, documents.update, collections.delete, and documents.archive. This is a direct contradiction of the stated safety profile. Per the rules this is an annotation contradiction and scores 1, despite the otherwise useful disclosure of URL, return payload, and pagination.

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

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

Front-loaded with purpose and the URL, then args and returns. The long enumeration of ~30 method names is bulky, but for an open-ended dispatcher it earns its place by giving the agent the exact method identifiers to pass, so the length is defensible rather than 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?

For an open-world proxy with a free-form params object, the description covers the transport, the required method argument, the params contract, and the return shape including pagination, so an agent can call it correctly. The one missing piece is any warning about the privileges/irreversibility of the destructive methods it lists, which matters a great deal here.

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% (method and params are both documented in-schema), so the baseline is 3. The description reinforces that method is a dotted name like 'documents.info' and that params is a 'method-specific payload', which is helpful context but adds no syntax or structure 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+resource ('Call any Outline RPC method directly') and pins the exact wire format (POST https://app.getoutline.com/api/:method), so the agent knows precisely what this does. It also differentiates itself from siblings by scoping to 'endpoints without a dedicated tool', which cleanly separates it from outline_get_document, outline_list_documents, etc.

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

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

Explicitly states the selection condition: use this for endpoints that lack a dedicated tool, which implicitly routes the agent to the sibling tools for everything else. The enumerated common methods help an agent confirm coverage, though it never names a concrete sibling as the preferred alternative for the overlapping cases (create/update/delete document), leaving some 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 declare this as a non-read-only, non-idempotent, non-destructive, open-world write, so the safety profile is covered elsewhere. The description adds that it returns the created collection, which is genuinely useful given there is no output schema, but says nothing about auth requirements or whether duplicates are rejected.

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?

Front-loaded with the core action and then a compact Args/Returns breakdown; every clause carries information. The list format is mechanical but wastes no words.

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

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

With no output schema, the "Returns: the created collection" line fills the return-value gap, and all four arguments are accounted for at least minimally. Only prerequisites/permission context is missing, which is a modest omission for a simple create 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 description coverage is only 50% (name and color are documented; private and description are not), yet the description compensates by labeling description as optional Markdown and private as defaulting to false, plus giving a hex example for color. This adds meaning the schema does not carry.

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 collection." The resource is distinct from siblings like outline_list_collections and outline_create_document, so an agent can tell what object is produced. However, it does not explicitly contrast itself with the other create/collection tools, so it falls short of the top band.

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, nor any prerequisites or preconditions (e.g. whether the collection must not already exist, or whether permission is needed). The reader is left to infer usage entirely 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?

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that — no mention of required permissions, Markdown rendering/validation behavior, rate limits, or whether a comment id is returned, so it does not clear the (lower) annotated-tool bar.

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 that are front-loaded with the action, which is good. The 'Args:' sentence, however, duplicates information the schema already carries at 100% coverage, so it does not fully earn its place.

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

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

For a simple three-parameter mutation with annotations and no output schema, the description is minimally viable: it conveys the action and the reply mechanism. It omits expected outcomes (created comment id, threading behavior) and any permission/error context that an agent would want before calling.

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 and their meanings. The inline 'Args:' list merely restates documentId/text/parentCommentId with no added syntax, format, length, or constraint detail, making this baseline 3.

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 document'), which clearly distinguishes it from the read-side sibling outline_list_comments. It does not, however, explicitly name or contrast itself 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?

The only usage signal is the parenthetical '(optional, to reply)' on parentCommentId, which explains one parameter rather than when to choose this tool. There is no guidance on prerequisites, threading rules, or how this relates to outline_list_comments or outline_create_document.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true. The description adds genuinely useful context beyond them — publish defaults to false and drafts are visible only to the author — but omits that repeat calls create duplicates (non-idempotent) and says nothing about required permissions for container placement.

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 sentences front-loaded with the purpose, then Args and Returns in a scannable structure. Every clause carries information, though the 'Args:'/'Returns:' shorthand is terse and the inline publish note is slightly crammed.

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

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

With no output schema, the description correctly states that the created document is returned, and annotations cover the safety profile. The remaining gap is the unexplained collectionId/parentDocumentId placement semantics for a mutation tool, which an agent likely needs to call it right.

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

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

Schema description coverage is 60%, and the description names all five parameters plus the required flag and the Markdown format for text. However, collectionId and parentDocumentId are named with no explanation of what they control or whether they interact, so the description only partially compensates for the uncovered schema fields.

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

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

States a specific verb (Create) and resource (document), which cleanly separates it from outline_create_collection and outline_create_comment without extra work. It is clear but never explicitly routes the agent or names an alternative, so it stops short of 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 description says nothing about when to use this versus outline_update_document, outline_move_document, or outline_get_document. No prerequisites or exclusions are given; the agent must infer the create-vs-update distinction entirely from the tool name.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered structurally. The description adds genuinely useful behavior the annotations do not convey: that the default operation is a reversible move to trash rather than an irreversible destruction. It stops short of noting auth requirements or restore paths for trashed documents.

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 action and followed by the parameter essentials. Nothing extraneous, and the reversible-default detail is placed where an agent will read it.

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 delete tool with full schema coverage and rich annotations, the description covers the essential default-vs-permanent distinction. It is slightly thin on consequences (what happens to a trashed document, whether the id remains valid), but nothing blocks correct invocation.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema, including the default and meaning of permanent. The description's 'id (required), permanent (default false — moves to trash when false)' largely restates the schema rather than adding format or edge-case detail, 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 ('Delete') and resource ('a document') with no ambiguity. It is cleanly separable from siblings like outline_update_document, outline_move_document, or outline_get_document.

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 key decision — default call trashes, permanent=true hard-deletes — which is real usage guidance for the tool's only flag. However, it never addresses when to delete at all versus alternatives such as trashing via update or moving a document, nor any prerequisites/permissions.

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/idempotent/destructiveHint, so the safety profile is covered, and the description is consistent with them (no contradiction). It adds that the response includes Markdown text, but says nothing about missing-document behavior or errors.

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, front-loaded with the action and resource, no filler. The trailing 'Args: id (string)' repeats the schema and is the only slightly wasted 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?

For a single-parameter read with full annotation coverage and no output schema, the description is adequate: it names the key resource and states that Markdown content is returned. Only the sourcing of the id and failure behavior are left implicit.

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

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

Schema description coverage is 100% with a single 'id' parameter, so the schema already carries the semantics. The description's 'Args: id (string)' merely restates the schema and adds no format or sourcing detail.

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

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

States a specific verb and resource ('Fetch a document by id') and adds the return-scope detail 'including its Markdown text', which separates it from retrieval-by-list siblings like outline_list_documents. It does not explicitly name an alternative, but 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 'by id' phrasing implies the use case (retrieve a single known document) but never says when to prefer this over outline_search or outline_list_documents, nor where the id is expected to come from. 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds a modest amount of behavioral context by calling the result a 'document tree', but says nothing about pagination limits, ordering, or how deep the tree goes.

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, front-loaded fragments with zero filler; the purpose sentence leads. The trailing args list is largely redundant with the schema but is brief enough not to be a real cost.

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

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

For a read-only list tool with full annotation coverage and complete schema documentation, the description is minimally adequate. With no output schema, though, it should say more about the returned tree shape and how paging interacts with a hierarchical result, and it should disambiguate from the sibling list 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%, so all three parameters (id, limit, offset) are already fully documented with types, defaults, bounds, and semantics. The description's 'Args:' line merely restates the parameter names, adding no format or constraint detail beyond the schema; 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 (document tree of a collection), and the phrase 'document tree' usefully signals a hierarchical result rather than a flat list. However, it never distinguishes itself from the close sibling outline_list_documents, leaving the agent to guess which listing tool to pick.

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

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

No when-to-use statement, no exclusions, and no alternatives named. The overlap with outline_list_documents and outline_list_collections is exactly the case where routing guidance is needed, and none is given; the only implicit hint is the required collection id.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered structurally. The description adds only the workspace scoping constraint; it says nothing about ordering, default page size behavior, or workspace-membership 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?

Two short sentences, front-loaded with the purpose. The trailing 'Args: limit, offset' is redundant with a fully documented schema, but the overall footprint is tight and non-wasteful.

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, non-destructive, zero-required-parameter list tool with full annotation coverage this is minimally sufficient. With no output schema, however, the agent gets no hint of what a collection record contains or how pagination termination works.

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 per-field descriptions and bounds (1-100, offset >= 0), so the schema does the heavy lifting. 'Args: limit, offset' merely restates the parameter names without adding format, interaction, or defaults guidance — baseline 3.

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 ('List all collections') and scope ('in the workspace'), which cleanly separates it from sibling list tools like outline_list_documents and outline_list_users. It does not explicitly name an alternative, 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?

There is no guidance on when to use this versus outline_list_collection_documents or outline_search, and no prerequisites or exclusions are stated. The only usage-adjacent text is 'Args: limit, offset', which is 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds nothing beyond that—no pagination behavior, no note on ordering, no coverage of comment threading or resolution state.

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?

It is short and front-loads the purpose, which is appropriate. The 'Args:' enumeration is largely redundant with a fully documented schema, so one small portion of the text does not earn its place.

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

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

For a simple paginated list tool with full annotation coverage, the description is minimally adequate. It omits any statement of what is returned (no output schema exists) and gives no pagination guidance, leaving the agent to infer result handling.

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/offset ranges and defaults documented in the schema itself, so the baseline is 3. The description's 'limit, offset' listing provides no semantics beyond the schema (no unit, ordering, or pagination interaction detail).

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

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

The description states a clear verb+resource ('List comments on a document'), which distinguishes it from the write-side sibling outline_create_comment. However, it does not name or contrast with any sibling list tools, so differentiation stops at the verb level.

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 prerequisites, and no mention of what happens with out-of-range values. The trailing 'Args:' clause is a parameter restatement, not usage guidance.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the safety and idempotency profile is covered. The description adds only the optional scoping context. It does not disclose pagination defaults (limit 25, offset 0) or return shape, which would be useful for an open-world read 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?

Single sentence with an arg list; front-loaded with the purpose and scoping. Efficient, though the trailing 'Args:' enumeration is low-value since parameters are already in the schema.

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

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

For a list tool with no output schema, the description should clarify return format, pagination behavior, and how collectionId vs parentDocumentId are used. It omits all of these, leaving the agent to guess interactions and paging.

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

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

Schema coverage is 50%: limit and offset are well described in the schema; collectionId and parentDocumentId have no schema descriptions. The description merely names the four args without explaining semantics (e.g., that the two scoping params are mutually exclusive or how they interact). It does not compensate for the coverage gap.

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 clear verb+resource ('List documents') with scoping qualifiers. However, it does not distinguish itself from siblings outline_list_collection_documents and outline_search, which also list/return documents. The purpose is adequate but lacks 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?

No explicit when-to-use or when-not-to-use guidance. The description implies scoping via optional params but does not route the agent to outline_list_collection_documents for collection-scoped listing or outline_search for queries. No alternatives 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds nothing behaviorally — no auth requirements, no pagination semantics beyond the schema, no indication of what a filtered result contains. It essentially restates the arg names.

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 sentence is front-loaded and tight, but the 'Args: query (optional), limit, offset' clause mostly duplicates schema field names and consumes space without adding meaning. Short, but not every element earns its place.

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

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

For a simple read-only list tool with ubiquitous annotations and no output schema, the definition is minimally adequate. It still leaves open what query filters on and how pagination interacts with results, which an agent would want before invoking 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 67%: limit and offset are documented in the schema, while query has no description there. The description only flags query as 'optional' (already implied by zero required params) without saying whether it matches name, email, or both. Marginal value over the schema, so the baseline 3 holds.

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 workspace users'. It is unambiguous against siblings like outline_list_documents or outline_list_comments, though it never explicitly differentiates itself — the disambiguation comes entirely from the resource noun.

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?

'optionally filtered' hints that a query exists but gives no when-to-use guidance, no condition selecting it over outline_search, and no note on what the filter matches. The agent must infer the use case.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the 'and/or' destination semantics and discloses nothing beyond structured data — no mention of permission requirements, effects on children of a moved parent document, or behavior when both optional arguments are omitted.

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

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

One short, front-loaded sentence followed by an inline arg list; nothing is padded. The 'Args:' enumeration largely duplicates the schema, but it is compact and does not obscure the primary statement.

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

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

For a mutation tool with no output schema and low schema description coverage, the description is thin: it omits permission needs, the effect of supplying only one of the two optional parameters, and confirmation of what a successful move changes. An agent cannot call this correctly in edge cases from the current text.

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

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

Schema description coverage is only 33% (just 'Document id'), so the description carries the burden for collectionId and parentDocumentId. It merely restates the parameter names, adding no meaning — it does not explain that these identify the destination collection and parent document, nor whether either is optional and what happens if both are absent.

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 (move) and resource (document) plus the two dimensions being changed (collection and/or parent), which is concrete and non-tautological. It is not explicitly differentiated from siblings like outline_update_document or outline_get_document, so an agent must 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?

There is no statement of when to use this versus update_document, no prerequisites (e.g., required permissions), and no note that at least one of collectionId/parentDocumentId should be supplied for the call to be meaningful.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds almost nothing beyond that: it says "Returns: matching documents" but omits ranking behavior, pagination semantics for limit/offset, and result ordering, despite this being a paginated search.

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 purpose, no filler. The "Args:" restatement is mildly redundant with the schema but not bloated.

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

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

For a four-parameter, fully-annotated search tool with no output schema, the description is minimally viable. It leaves gaps around sibling disambiguation and pagination/ranking behavior that an agent would need to call it confidently.

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

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

Schema coverage is 75%, so most parameters are self-documenting. The description merely restates the args (query string, collectionId optional, limit, offset), adding only the "optional" flag on collectionId, which is already implied by the required list. Baseline 3 is appropriate 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?

"Full-text search across documents" states a clear verb+resource, so the agent instantly knows the operation. However, it offers no differentiation from the very similar sibling tools (outline_list_documents, outline_list_collection_documents), which an agent could easily confuse with a search.

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

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

There is no guidance on when to use this versus browsing tools like list_documents, nor any note on when collectionId should be supplied. Usage is only implied by the word "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?

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds that text replaces the body (a behavioral detail about mutation), which is useful beyond the annotations. It does not mention authentication requirements, rate limits, or how existing title/body values are handled when only one field is supplied.

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 plus a brief Args listing and a Return statement. It is front-loaded with the main action and contains no unnecessary filler. However, the Args section largely repeats the schema and could be omitted in favor of richer behavioral detail.

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

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

With no output schema, the description correctly states that it returns the updated document. But for a mutation tool with openWorldHint and no idempotency guarantee, the description omits important context such as whether partial updates are allowed (i.e., what happens if only title or only text is provided), whether updates are reversible, and any side effects. These gaps reduce completeness.

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 67%, so some parameters are already documented in the schema (id and text). The description adds the note that text replaces the body, which matches the schema but does not add new syntax or format information. The title parameter lacks a schema description, yet the description only names it without clarifying constraints or format.

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 (Update) and resource (document), and enumerates the mutable fields (title and/or body). It is clearly distinguishable from siblings like create_document or delete_document. However, it does not differentiate from move_document, which also updates a document, so it falls just short of a 5.

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

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

There is no statement of when to use this tool versus alternatives such as outline_move_document or outline_get_document. The only implicit guidance is that it can update title or body, but no context, exclusions, or prerequisites are provided.

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