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

With no annotations, the description carries the burden and does well: it discloses reversibility, the side effect of removal from the collection, and restorability from the archive. It does not mention permissions or whether archiving an already-archived document is idempotent, so it stops short of full disclosure.

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

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

One sentence, zero filler, with the key semantic fact (reversible) surfaced immediately in parentheses and the routing advice last. Every clause earns its place.

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

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

For a one-parameter mutation tool with no annotations and no output schema, the description covers the essential behavior (reversible removal) and the sibling choice. Missing only peripheral details like permission requirements or the archive's subsequent retrieval path.

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

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

Schema coverage is 100% and the single 'id' parameter is documented in the schema, so the description need not explain it. It adds no format hints or constraints beyond the schema, which is the baseline-3 case.

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 (Archive) and resource (document), and adds the semantic consequence: it disappears from the collection but is restorable. This distinguishes it from the update/delete family without needing a schema.

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

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

Explicitly routes the agent: 'Prefer this over delete_document.' That is real when-to-use guidance. It loses a point because delete_document is not among the listed siblings and no when-not (e.g., when to genuinely delete instead) is 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?

With no annotations, the description carries the full behavioral burden, and it does disclose the highest-value traits: documents are published (public) by default, drafts are opt-in via publish=false, and collectionId is mandatory. It omits permission requirements, whether published posts are externally visible, and error behavior, which are meaningful gaps for a write tool without annotations.

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

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

Three tight sentences, front-loaded with the core action, then defaults, then the required-parameter dependency and optional nesting. No filler and no restatement of the title.

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

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

For a 5-parameter create tool with no output schema and no annotations, it covers the essentials an agent needs to invoke correctly: required inputs, default visibility, draft escape hatch, sourcing of collectionId, and nesting. It would be complete at 5 if it mentioned auth/permission prerequisites or that the new document's id is what subsequent update_document calls need.

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

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

Schema description coverage is already 100%, so the baseline is 3. The description adds genuine value beyond the schema by telling the agent where collectionId comes from ("use list_collections") and by surfacing the publish default as a decision point rather than a passive field default; the remaining field mentions repeat schema text.

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

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

States a specific verb and resource ("Create a new Outline document from markdown") and immediately adds the two behavioral facts that matter most: default published state and the required collectionId. It is clearly the creation tool among the siblings, though it never explicitly contrasts itself with update_document/move_document, so it stops short of full sibling differentiation.

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

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

Gives concrete decision context: pass publish=false to save a draft, retrieve collectionId via list_collections, and optionally nest via parent. It names an alternative tool (list_collections) with the condition that selects it, but offers no guidance on when to prefer this over update_document or when creation would fail (e.g., missing permissions, duplicate names).

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

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

With no annotations, the description carries the behavioral burden and does so reasonably: 'Get' signals a non-mutating read, and it discloses the shape of the returned structure (ids, titles, nesting), compensating for the absent output schema. It omits permission requirements, error behavior, and whether large collections are paginated.

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

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

Two sentences, zero filler, with the core action and payload shape front-loaded ahead of the usage hint. Every clause earns its place.

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

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

For a single-parameter read tool with no output schema, the description sufficiently covers what the tool returns (document tree) and when to reach for it. Minor gaps remain around permissions and pagination of the document tree, but nothing essential to invoking it correctly is missing.

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

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

Schema coverage is 100% and there is only one parameter ('id', documented as 'Collection id'), so the schema already carries the semantics. The description adds no format hints or id-source guidance beyond what the schema provides, which is the baseline-3 case.

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 ('Get one Outline collection') and even previews the payload ('document tree (ids, titles and nesting)'), which lets an agent tell it apart from get_document. It does not explicitly distinguish itself from the sibling list_collections by name, 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?

'Useful to understand how a collection is organised before creating or moving documents' gives a concrete when-to-use context and implicitly routes to create_document/move_document workflows. There is no when-not to use it or explicit mention of the read-only list alternative, so it stops at a clear-context 4.

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 burden; it does disclose that the full markdown body is returned, which is useful return-value context absent an output schema. However, it says nothing about permissions, error behavior for missing documents, or how share ids differ in access.

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 return content, with zero filler. Every clause contributes information.

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

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

For a single-parameter read tool with no output schema, the description covers what is fetched and the accepted identifier forms, which is sufficient to invoke it. Minor gaps around access requirements and not-found behavior are the only omissions.

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

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

Schema coverage is 100% and there is only one parameter, so the baseline is 3. The description largely restates the schema's 'Document id, urlId or share id', adding only a brief gloss that urlId is the slug portion of the URL.

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 ('Fetch') and resource ('a single Outline document') and clarifies it returns the full markdown body, which implicitly separates it from list_documents and search_documents. It does not, however, explicitly name or rule out any sibling tool, so differentiation remains inferential.

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 note that it accepts a document id, urlId or share id implies the tool is for retrieval when you already hold an identifier, but there is no explicit when-to-use guidance or statement of when to prefer search_documents/list_documents instead.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses the return fields (id, name, description, url), which substitutes for the missing output schema, but says nothing about pagination behavior, ordering, or the limit/query interaction that a listing tool needs.

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

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

Three short sentences, zero filler, with the resource definition and the primary downstream use case front-loaded. Nothing needs to be trimmed.

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 compensates by naming the returned fields, and it explains the resource relationship to documents. It is slightly incomplete on listing mechanics (default limit, pagination), but an agent has what it needs to call the tool.

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

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

Schema description coverage is 100%, so both parameters (limit, query) are already fully documented in the schema, including the substring-match semantics for query. The description adds no parameter detail beyond that, 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 (List) and resource (Outline collections), and even defines the resource as 'top-level groupings of documents', which removes ambiguity against get_collection and the document-level siblings. An agent can tell exactly what this returns without opening the schema.

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

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

It gives downstream guidance ('Use the id with search_documents, list_documents or create_document'), which is workflow help rather than selection guidance. It never says when to prefer this over get_collection or the document listing tools, so usage is only implied.

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

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

There are no annotations, so the description carries the full behavioral burden. It usefully discloses the return shape (id, title, url, timestamps, no bodies) and the default sort, but says nothing about pagination behavior, total counts, permissions, or what happens when a collectionId/parentDocumentId matches nothing.

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: the first gives scope and filters, the second gives the return shape and default ordering. Nothing is padded and the most decision-relevant information leads.

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 compensates by enumerating returned fields and excluding bodies. For a six-parameter read tool with no required args, this is nearly sufficient, though how limit/offset paginate the result is left unstated.

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

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

Schema coverage is only 33%, and the description only adds meaning for collectionId/parentDocumentId (already documented in the schema) plus the default sort. The limit, offset, direction enumerations, and the distinction between 'index' and other sort modes are left entirely to the schema.

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

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

States a specific verb and resource (list documents) plus the two optional filters (collection, parent document) and a default ordering rule, which an agent can distinguish from a get or search tool. It does not explicitly name siblings such as search_documents or get_document, so the differentiation is implicit rather than stated.

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

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

Usage is implied by 'optionally filtered by collection and/or parent document', which hints at when to reach for it over a full-text search, but there is no explicit when-to-use/when-not statement and no named alternative tool. An agent must infer the boundary against search_documents and get_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?

No annotations are provided, so the description carries the full behavioral burden. It states the top-level default when parentDocumentId is omitted, but says nothing about required permissions, what happens to child documents or sibling ordering, or whether the move is reversible.

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

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

Two sentences, zero filler, with the primary action front-loaded and the defaulting rule immediately after. Every clause earns its place.

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

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

For a 4-parameter mutation tool with no annotations and no output schema, the description is adequate on purpose and the parentDocumentId default but silent on permissions, side effects, and index behavior. Enough to call it, not enough 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 100%, so the baseline is 3, and the description earns above that by explaining the semantic effect of omitting parentDocumentId (move to collection top level). It does not add comparable meaning for collectionId or index, so it stops short of a 5.

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

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

The description names a specific verb and resource ('Move a document') and further narrows scope to relocating it across collections and/or parents. This clearly separates it from list/get/archive siblings, though it never explicitly contrasts with update_document, which is the nearest conceptual neighbor.

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

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

Usage context is implied by the scope statement (relocate within a collection hierarchy), and one behavior is spelled out ('Omit parentDocumentId to move it to the top level'). However, there is no explicit guidance on when to reach for this tool versus update_document or archive_document, nor any 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 to carry the burden, the description steps up by disclosing exactly what each hit contains (id, title, url, snippet) and what it deliberately omits (document bodies). It says nothing about permission requirements, result caps, or empty-result behavior, keeping it below a 5.

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

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

Two sentences, zero filler, and the return-shape constraint is front-loaded before the routing hint to get_document.

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?

No output schema exists, so the description must describe returns — and it does, listing the per-hit fields and the missing body. It leaves pagination semantics (offset/limit interplay) unaddressed, a minor gap for a search tool of this size.

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 query, limit, offset and collectionId are already documented in structured form; the description adds nothing about them. Baseline 3 applies 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?

Names a specific verb and resource ('Full-text search across Outline documents') plus the shape of the hits, which clearly separates it from list_documents. It does not explicitly name the sibling it is not (list_documents), 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?

Provides a clear follow-up path: hit ids are meant to be fed to get_document, and it explicitly rules out reading bodies here. It offers no guidance on when to prefer search_documents over list_documents, so it lacks the exclusion half of a 5.

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

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

With no annotations, the description carries the full burden and does disclose the two most non-obvious behaviors: `text` REPLACES the body by default, and only passed fields are changed (partial update). It is silent on side effects like the notification trigger for `done` or draft-publishing via `publish`, which the schema mentions only in passing.

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

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

Three short sentences, front-loaded with the core action before the append nuance and the partial-update guarantee. No filler, though the final sentence slightly overlaps the second in intent.

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 six-parameter mutation with no output schema, the description covers the tricky semantics (replace vs append, partial update) that an agent most needs. The remaining gaps (done/publish side effects) are documented in the schema, so the definition is close to sufficient.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters (including id, done, publish). The description reinforces the text/append interaction and partial-update semantics but adds no new parameter detail beyond that baseline.

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

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

States a specific verb (update) and resource (existing document) plus the editable fields (title, markdown body). It is clearly distinct from the create/move/archive/get siblings by name and scope, though it does not explicitly name them.

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

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

Usage is implied rather than stated: an agent can infer 'use this to modify an existing doc' versus create_document. There is no explicit when-to-use/when-not guidance or reference to any sibling, so it stops at the minimum viable level.

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