Docmino

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The phrase "using its current revision" usefully implies optimistic concurrency (the call is tied to a specific revision), but the description never says whether archiving is reversible, what happens on a revision mismatch, or what permissions are required.

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 with zero filler and the verb first. Its brevity is efficient, though it edges toward under-specification rather than tightness.

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

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

For a destructive, non-read-only mutation with two undocumented required parameters, the description omits reversibility, failure behavior on stale revisions, and its relationship to delete_document. The existence of an output schema excuses it from explaining return values, but the behavioral gaps remain significant.

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

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

Schema description coverage is 0%, so the description carries the full burden. It hints that expectedRevision means the document's current revision, but gives no format, no explanation of what happens when it doesn't match, and never mentions the id parameter at all.

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 ("Archive a document"), so the action is unambiguous. However, it offers no differentiation from the closely related sibling delete_document, leaving the agent to guess whether archive is a softer/reversible alternative to deletion.

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

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

There is no guidance on when to archive versus delete_document, nor any prerequisite (ownership, permissions, document state) for archiving. The agent must infer the entire selection context from the verb 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?

Annotations already declare the write, non-idempotent, non-destructive profile, so the description's modest addition (that pages nest arbitrarily via a tree) is worth some credit. It stays at 3 because it never says what happens on duplicate slug or name, whether projectId/workspaceId are required in practice despite zero required params, or what a repeat call produces given idempotentHint=false.

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

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

Two short sentences with the core purpose front-loaded and no filler. The second sentence is copied verbatim from the content parameter's schema description, which is mild duplication rather than an independent contribution.

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

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

An output schema exists, so return values need no explanation, and the annotations carry the safety profile. The description covers the one non-obvious structural behavior (recursive page tree) and points to the authoring guide for body syntax, which is enough 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?

Schema description coverage is only 25% (content and tags), so the description must compensate and largely doesn't. It explains the content/pages pair but says nothing about projectId, workspaceId, slug, name, or summary, leaving half the parameters undocumented in both places.

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 (creates a Docmino document) plus the two defining payload traits: MDX content and an optional nested page tree. It does not name update_document or otherwise tell the agent how it differs from sibling write tools, which keeps it below 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 routing guidance is a pointer to get_authoring_guide for component syntax, which covers one sub-task but not the main create-vs-update decision. Nothing says when to use create_document rather than update_document, or under what conditions a create is appropriate.

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 disclose readOnly=false, idempotent=false, destructive=false and a closed-world scope, so the safety profile is covered. The description adds only the workspace scoping detail; it does not mention whether duplicate names are allowed, whether the creator becomes owner, or what permissions are required for organization workspaces.

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

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

A single front-loaded sentence with zero wasted words. Brevity here reflects correct structure, though it borders on under-specification rather than crispness.

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

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

An output schema exists so return values need no explanation, but this is a non-idempotent mutation with four undocumented parameters and no annotations covering permissions or side effects. The description leaves too much for the agent to guess about a write operation.

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

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

Schema description coverage is 0%, so the description must compensate. It partially does: 'personal or organization workspace' implies what workspaceId selects and that omitting it likely defaults to the personal workspace. It says nothing about the distinction between 'description' and 'instructions' or the 6000-character limits, so half the ambiguity remains.

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 project') plus the scope ('personal or organization workspace'), which is enough to distinguish it from create_document and other siblings. It stops short of explicitly naming or contrasting with sibling tools such as update_project or list_projects.

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 siblings, no prerequisites (e.g., required role or permissions), and no exclusions. The agent must infer usage purely 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is structured. The description's one added fact — that pages are deleted along with the document — is genuinely useful cascade information not present in the annotations, but it stops short of saying the deletion is irreversible or whether confirmation/recovery exists.

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

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

One short sentence, front-loaded with the verb and resource, with zero filler. Its brevity is slightly under-specified for a destructive operation rather than wordy, but there is no wasted text to trim.

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 irreversible, destructive, cascading operation, the description omits permanence/recovery, permission requirements, and how the id is obtained. The output schema exists so return values needn't be explained, but the behavioral gaps around a delete are significant.

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

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

Schema description coverage is 0%, so the single required parameter 'id' is documented nowhere. The description implies the identifier refers to a document, which is the minimum needed to use it, but it adds no format, source (where to obtain the id), or behavior for invalid ids.

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?

"Delete a document and its pages" states a specific verb (delete) and resource (document), and adds scope detail — the deletion cascades to the document's pages. It does not differentiate from the sibling archive_document, so an agent must infer on its own which of the two is the soft vs hard removal path.

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 when-to-use guidance and no mention of the obvious alternative, archive_document, which is present in the sibling list. The description also gives no prerequisites (ownership, permissions) or warning about when to prefer archiving over permanent deletion.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: contained documents are released rather than deleted, are retained, and their inherited access can change — a consequence an agent could not read off the annotations.

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

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

Two tight sentences with the action front-loaded and the side effect immediately after. Every clause adds information; nothing is padded or redundant.

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

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

An output schema exists and annotations cover safety and idempotency, so the description only needs to fill the behavioral gap, which it does by explaining document retention and access changes. The missing piece is document identification of the 'id' argument, but otherwise it is complete enough to call 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 has zero description coverage for the single required 'id' parameter, so the description must carry the burden. It never mentions the identifier at all — not what kind of project ID is expected, nor whether it is the project GUID or slug — leaving the only input undocumented in prose.

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 ('Delete a project') and the second sentence clarifies the post-delete effect on contained documents. It does not differentiate from sibling tools like delete_document or archive_document, so an agent must infer which deletion path applies.

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 archive_document or delete_document, nor any stated preconditions (permissions, empty-project requirements, confirmation). The agent is left to infer the appropriate call site from the name 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is fully covered without the description. The one genuine addition is that large documents return explicit continuation instructions, which reveals truncation behavior; however it never says what the continuation looks like (cursor, next-call argument, page index), so the agent still cannot plan the follow-up.

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 followed by the one behavioral caveat. No filler, though the brevity comes partly from omitting information that would actually be useful.

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, annotated, output-schema-backed read tool this is close to sufficient in mechanics, but the unresolved identity of `id` and the absence of any differentiation from get_document/open_document leave real gaps. The continuation hint is present but underspecified.

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 `id` has zero schema description coverage and the description says nothing about it. It does not state whether the id refers to a document, a revision, a page, or a workspace-scoped identifier, which matters given the sibling list mixes document and page tools. Output schema presence relieves the return-value burden but not the input ambiguity.

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?

"Retrieve a Docmino document" names a verb and resource, but the sibling list contains get_document, open_document and read_page, and the description makes no effort to distinguish this tool from any of them. An agent cannot tell from the text alone whether fetch is a synonym for get_document or serves a different access path.

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 when-to-use guidance and no exclusions. With four document-reading siblings (fetch, get_document, open_document, read_page) the definition gives the agent nothing to route on, leaving selection to guesswork or trial and error.

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 it read-only, idempotent, non-destructive, and closed-world. The description adds useful behavioral context beyond that: the default guide covers common components, while component selection returns focused schemas and examples with companion components automatically included.

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 front-loaded sentences with no wasted language. The default behavior and component-selection behavior are both stated efficiently.

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 one optional parameter, an output schema, and annotations covering safety semantics. The description supplies the remaining needed context: what the guide contains, what the default returns, and how component selection changes the result.

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

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

Schema coverage is 100%, so the schema already documents the optional components parameter and enum. The description still adds value by explaining the effect of selecting components: focused schemas and examples rather than the default guide, with companion components included automatically.

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

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

The description states a specific verb and resource: it returns Docmino's MDX authoring documentation for document and page content, including component props and examples. This is clearly distinct from the sibling tools, which manage documents, projects, shares, and pages rather than authoring guidance.

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

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

It explains the two usage modes: omit components for the default common-component guide, or provide component names for focused schemas and examples. It does not explicitly state when not to use the tool or name alternatives, but the intended usage context is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is met; the description adds real value by disclosing that the snapshot is editable and that the full page tree must be preserved on save — a non-obvious data-loss hazard invisible from the schema. It stops short of stating whether the revision is required for subsequent updates.

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

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

Two tight sentences, front-loaded with the core action and followed by the one operational caveat. No filler or restatement of the title.

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

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

The output schema covers return values, so no explanation is needed there, and the save-time warning is useful. But with a fully undocumented required parameter and no sibling differentiation, an agent still lacks enough to call this confidently against adjacent retrieval 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 0% for the single `id` parameter, and the description never mentions it — it does not say whether `id` is a document id, page id, or revision token, an ambiguity that matters given sibling tools that operate on pages. The description provides no compensating meaning.

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 the ... document snapshot and revision") and clarifies the payload is the full editable document rather than a single page. It does not, however, distinguish itself from close siblings like open_document or read_page, so the agent must infer which retrieval tool applies.

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 statement of when to use this instead of read_page, open_document, or list_documents. The trailing clause "Preserve the full page tree when saving" hints at the edit-then-save workflow but is a downstream caution, not a usage rule for selecting this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds two useful behavioral facts beyond that: results are permission-scoped (only accessible projects) and a canonical link is included. It says nothing about behavior when the id is missing or inaccessible, which is a real gap for a lookup 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?

A single front-loaded sentence with no filler; the resource and its scope appear before the return detail, and nothing is wasted.

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

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

With a rich annotation set and an output schema in place, the description only needs to establish purpose, access scoping, and the id's meaning, and it does most of that. The remaining omission is error behavior for a missing or unauthorized project id.

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

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

Schema description coverage is 0%, so the description must carry the load; "project's" is the only clue that the id parameter identifies a project rather than a document, page, or share. It never states the id format or where to obtain one, so it only partially compensates 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?

The description pairs a specific verb ("Retrieve") with a specific resource ("an accessible project's details") and notes the canonical Docmino link it returns. That clearly separates it from list_projects and list_project_documents, though it never explicitly names those siblings.

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

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

There is no explicit when-to-use guidance, no when-not-to-use, and no named alternative for finding a project id (e.g., list_projects). The word "accessible" hints that permissions gate the result, but the agent is left to infer the calling 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?

Annotations already declare the safety profile (destructiveHint=true, idempotentHint=false, openWorldHint=true), so the bar is lower. The description adds one genuinely new trait — that invitations send notifications, i.e. an outbound side effect — but says nothing about what happens when the recipient already has access, whether re-inviting is rejected, or that the operation creates a persistent share entry.

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 scope, with the notification caveat placed last. No filler.

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

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

An output schema exists, so return values need no explanation, and the safety profile is annotation-covered. Still, for a destructive, non-idempotent mutation the description should mention duplicate-share behavior and permission requirements; those gaps leave an agent guessing.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It usefully explains that target is a document or project and that recipient may be a user, email, or phone — matching the three anyOf branches — but leaves 'id' (which entity's id) and the role enum (ADMIN/EDITOR/VIEWER effects) entirely unexplained.

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 concrete verb (grant access) and the resource types (document or project) plus the recipient shape, which clearly separates it from list_shares, update_share and remove_share. It stops short of explicitly naming those siblings, so 4 rather than 5.

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

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

Usage is implied by the action itself, and the note that invitations send notifications hints at a real-world side effect, but there is no explicit when-to-use vs. when-to-use-update_share guidance and no stated prerequisites such as needing owner/admin rights on the target.

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=false and destructiveHint=false, so the safety profile is fully covered. The description adds the workspace scoping rule and the account-level fallback, which is useful, but says nothing about ordering, pagination mechanics, or result size beyond the word 'paginate'.

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 core action and followed immediately by the one non-obvious scoping rule. No filler, though it is arguably too terse for a four-parameter search tool.

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

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

An output schema exists, so return-value explanation is rightly omitted. But for a search/list tool with four undocumented parameters and a name that conflicts conceptually with the `search` sibling, the description leaves the agent guessing about query semantics and pagination.

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

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

Schema description coverage is 0%, so the description must compensate for all four parameters, and it only explains `workspaceId` (omit to scope to your account). It says nothing about what `query` matches (title, content, metadata) or about `limit`/`offset` behavior.

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

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

States a specific verb ('Search and paginate') and resource ('documents accessible in a workspace'), so the agent knows exactly what operation it performs. However, it never distinguishes itself from siblings like `search`, `get_document`, or `list_project_documents`, which is a real ambiguity given the overlap in intent.

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 guidance is a parameter-scoping note ('Omit workspaceId for your account'). There is no statement of when to prefer this over `search` or `list_project_documents`, nor any exclusion or prerequisite.

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, destructiveHint=false, so the safety profile is covered. The description adds real value by stating content is excluded and nesting/revision are included, but says nothing about pagination defaults, page-size behavior, or what expectedRevision does on a read call.

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 tight sentence with zero waste; the distinguishing qualifier ('without content') is front-loaded and the additional return characteristics follow 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?

An output schema exists, so return values need no explanation, and the annotations cover safety. However, for a 4-parameter tool with no schema documentation, the description leaves the pagination and revision parameters opaque, which is a meaningful completeness gap.

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

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

Schema description coverage is 0% across 4 parameters, so the description must carry the burden and it does not: id, limit, offset, and especially expectedRevision (an optimistic-concurrency parameter on a read tool) are entirely unexplained. An agent cannot tell from the text whether expectedRevision filters or asserts state.

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

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

States a specific verb and resource ('List all document pages') plus scope qualifiers: metadata only ('without content'), nesting included, current revision returned. This clearly separates it from read_page, though it never names the sibling explicitly.

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

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

Usage is only implied: an agent can infer this is the metadata-first step before read_page / get_document, but the description contains no explicit when-to-use, when-not, or alternative-naming 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 readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds that results are paginated and filtered to what is 'accessible' in a project, which implies permission-scoped visibility, but it does not state ordering, page-size defaults, or total-count behavior.

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

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

A single front-loaded sentence with no waste. Its brevity is efficient, though it shades into under-specification given the undocumented parameters.

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

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

An output schema exists so return values need not be explained, and annotations cover safety. The remaining gap is the ambiguity of the required 'id' parameter and the pagination contract, neither of which is addressed.

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

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

Schema description coverage is 0% across three parameters, so the description must carry this burden and it does not. Nothing says that 'id' is a project identifier rather than a document ID, and no pagination mechanics (limit default 20, max 50, offset) are conveyed beyond the generic word 'paginate'.

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 and adds the scoping qualifier 'accessible in a project', which separates it from the general list_documents sibling. It does not name that sibling explicitly, 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?

Gives no guidance on when to use this versus list_documents, search, or get_project. The agent must infer that this is the project-scoped variant purely 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 establish read-only, idempotent, non-destructive, closed-world behavior. The description adds useful scope detail that shared projects are included, but does not mention pagination behavior or how accessibility is determined.

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

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

The definition is a single front-loaded sentence with no wasted wording. It is efficient, though its brevity leaves important parameter and usage details unstated.

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 low-complexity and has an output schema plus rich annotations, so return format and safety do not need explanation. However, with three undocumented parameters and no usage guidance, the description is only minimally complete for correct invocation.

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

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

Schema description coverage is 0% and the description does not mention any of the three parameters (limit, offset, workspaceId). It provides no meaning beyond the field names, leaving the workspace filter and pagination semantics entirely undocumented.

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

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

The description gives a specific verb ('List') and resource ('projects') plus a scope ('accessible, including shared projects'). It is clearly distinguishable from get_project and create_project, though it does not explicitly differentiate from other list_* siblings.

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

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

Usage is only implied by the phrase 'List accessible projects'; there is no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as get_project for a single project or list_workspaces for workspace 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description's only added context is that pending invitations are included alongside active shares, which is useful but thin. Return shape and pagination behavior are not discussed (mitigated 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?

One tight, front-loaded sentence with no filler. It is efficient, though arguably too sparse for a four-parameter tool.

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

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

An output schema exists and the annotations carry the full safety profile, so the description need not explain return values or side effects. The remaining gap, parameter meaning, is scored separately under parameter semantics.

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

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

Schema description coverage is 0% for 4 parameters. The description only obliquely gestures at the 'target' enum via 'document or project', and says nothing about the required 'id', 'limit', or 'offset'. With no schema-level documentation, the description should have carried this burden and does not.

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 ('direct document or project shares and pending invitations'), which cleanly separates it from the mutating siblings invite_share, remove_share, and update_share. It does not, however, name any sibling explicitly to reinforce the distinction.

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: this is the read tool for inspecting existing shares. The phrase 'direct ... and pending invitations' hints at scope, but there is no statement of when to prefer this over searching or fetching a document/project, and no prerequisites mentioned.

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-destructive, idempotent read operation, so the safety profile is covered. The description adds some scope by saying it returns personal and organization workspaces, but it does not disclose pagination behavior or ordering despite the limit/offset parameters.

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

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

The description is a single front-loaded sentence with no wasted wording. It is appropriately brief for a simple list operation, though its brevity contributes to missing behavioral and parameter 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?

The tool is simple, read-only, and has both annotations and an output schema, so the description need not explain return values or safety. However, it omits pagination semantics for the two parameters and does not state whether the personal workspace is always included or how results are ordered.

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

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

Schema description coverage is 0%, so the schema supplies only names and constraints for limit and offset. The description does not mention pagination or explain how those parameters affect the result, leaving the agent to infer standard limit/offset semantics.

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

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

The description gives a specific verb and resource ('List ... workspaces') and adds useful scope by distinguishing personal from organization workspaces. It does not differentiate from any sibling tool, but no sibling is a direct workspace-listing 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 states what the tool does but gives no explicit guidance on when to call it, when not to call it, or which alternative to prefer. Usage is only implied by the tool name and resource listed.

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 supplied. The description adds real value with 'This can change who has access', which tells the agent the permission surface is affected — but it omits the concurrency/revision-check behavior implied by expectedRevision and says nothing about what happens to shares on the document.

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 followed by the consequence. Nothing is wasted, though the second sentence is vague about what 'can' means in practice.

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?

Return values are covered by the output schema, but for a destructive, revision-guarded move with three required undocumented parameters, the description is missing the details an agent needs to call it correctly, notably revision semantics and the null projectId case.

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

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

Schema description coverage is 0% across 4 parameters, so the description must carry the load and does not. It gestures at project/workspace targeting but never explains that projectId is nullable (moving out of a project), what expectedRevision is for, or what id refers to.

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: moving a document to a project or workspace. That is clear enough to separate it from most siblings, though it never explicitly contrasts with move_project or explains how a document move relates to update_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 never says when to choose move_document versus move_project, or when to supply workspaceId instead of projectId. The only guidance sentence is a side-effect warning, not 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?

Annotations already declare destructive, idempotent, open-world, non-read-only, so the safety profile is known. The description adds one genuinely useful behavior beyond them: documents are moved along with the project. It omits whether the move is reversible, how existing shares/collaborators are affected, and any rate or permission constraints — notable gaps for a destructive operation.

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

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

A single front-loaded sentence with no filler. It is efficient, though arguably too terse for a destructive move operation.

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

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

An output schema exists so return values need not be explained, and annotations carry the safety profile. Still, for a destructive cross-workspace move with zero parameter documentation, the description should state at minimum what the two inputs identify and what happens to the project's existing sharing configuration.

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

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

Schema description coverage is 0% and both parameters (id, workspaceId) are undocumented in the schema. The description only obliquely implies that one parameter names the destination workspace; it never says what 'id' is or what format either expects, so it fails to 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?

Specific verb+resource ('Move a project') with the important scope detail that the project's documents travel with it, which separates it from move_document. It never names the sibling alternatives or states what happens to workspace-scoped shares, so it stops short of full 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 indication of when to use this instead of move_document, nor any prerequisite such as required permissions or whether the caller must own/administer both workspaces. The agent is left to infer everything about selection.

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 non-destructive closed-world behavior, so the safety profile is covered. The phrase 'with explicit Save' adds a small amount of editor-behavior context (nothing persists until an explicit save), but the description doesn't explain what 'opening' returns or whether a session/lock is created.

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 the primary action is front-loaded, but the second sentence about uploads and AI assistance is off-topic for this specific tool and consumes half the description without adding task value.

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

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

Rich annotations and an output schema reduce the burden, but the description still omits what the id refers to, when this is preferable to get_document/read_page, and what 'opening the editor' practically means. For a 1-param launch tool it leaves too much to guesswork.

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

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

Schema description coverage is 0% and the single 'id' parameter is undocumented in both schema and description. The description never states that the id identifies the document to open, so an agent must infer the most important parameter's meaning.

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 verb ('Open') and a product-specific resource ('the rich Docmino editor'), but it never says explicitly that it opens a document by id, nor how it differs from siblings like get_document or read_page. An agent can guess it launches an editing surface, but the purpose stays fuzzy.

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 guidance is 'Use Docmino for uploads and AI assistance', which describes the broader product, not when to call this tool versus get_document, read_page, or update_document. No when-to-use, when-not-to-use, or alternative is given.

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

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

The annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=true, and readOnlyHint=false. The description adds useful context that publishing can make content public, which is a meaningful risk beyond the annotations, but it does not explain permissions, concurrency behavior, or how unpublishing affects existing public 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 with no wasted words, and the public-exposure warning is appropriately front-loaded after the core purpose. It is concise and readable, though for a destructive five-parameter tool it may be too terse to be fully useful.

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 incomplete for a destructive, open-world mutation tool with five parameters and 0% schema description coverage. Even though an output schema exists, the description omits required parameters, enum meanings, concurrency requirements, and the practical effects of changing publication settings.

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

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

Schema description coverage is 0% for all five parameters, so the description must compensate and it largely does not. It vaguely gestures at publication status and access scope but never mentions required parameters like id and expectedRevision, nor explains the DRAFT/PUBLISHED enum or the listedPublicly flag.

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 and resource: change publication and public access settings. It is specific enough to distinguish the tool's domain from generic document updates, but it does not explicitly differentiate it from siblings like update_document or archive_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 gives no explicit guidance on when to use this tool versus alternatives. The sentence 'Publishing can make content public' is a consequence warning, not usage guidance, and there is no mention of prerequisites or when not to use it.

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 safe, idempotent, non-destructive, and closed-world, so the bar is lower. The description adds genuinely new context (chunked reads and cross-chunk revision checking), but omits how iteration terminates, what happens on a revision mismatch, or whether expectedRevision failing throws an error.

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, with the primary action front-loaded and the revision caveat second. No filler, though the second sentence is terse enough to be slightly cryptic about terminology.

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

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

An output schema exists, so return-value documentation is not needed. The remaining gap is just iteration/error behavior for a read-only, idempotent tool, which is minor against the annotation coverage. The description is adequately complete for such a 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 0%, so the description carries the full burden. It hints at the role of contentLimit/contentOffset ('in chunks') and expectedRevision ('Check revision'), but never explains the required id vs optional pageId distinction, defaults, or offsets semantics.

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

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

States a specific verb (read) and resource (document root content or a named page) and adds the chunked delivery characteristic. It does not distinguish itself from the very similar siblings get_document and open_document, so an agent must still infer which one 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?

'Read ... in chunks' and 'Check revision across chunks' imply this is for incremental/paged reading, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g., 'use get_document for full content'). Usage must be inferred 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?

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that by naming exactly what is destroyed: an active direct-access grant or an unaccepted invitation. It stops short of stating permission requirements (owner/admin only) or what happens to the recipient's session 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?

A single front-loaded sentence with the verb first and zero filler. Every word carries information and nothing is repeated from the title.

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

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

An output schema exists, so return values need no explanation, and the tool is structurally simple. However, for a destructive one-parameter tool the description leaves open which id to pass and what permissions are required, gaps that matter 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?

One required parameter 'id' with 0% schema description coverage; the description says nothing about it. It is unclear whether the id identifies the share entry, a user, or a workspace member, which is a meaningful ambiguity for a destructive call. The description does not compensate for the missing schema documentation.

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

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

Specific verb (revoke) plus a precise resource definition: 'a direct access grant or pending invitation'. This clarifies that a 'share' covers both an active grant and an outstanding invite, which an agent cannot infer from the name alone. It does not explicitly contrast with update_share or invite_share, but the verb-revoke framing makes the operation distinct.

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

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

Usage is implied by the verb (use when access must be removed) but there is no explicit when-to-use statement, no prerequisites, and no reference to alternatives such as update_share for downgrading access or archive/delete for larger scope. The agent must infer the boundary itself.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds useful scope by saying only 'accessible' documents are searched and that matching covers name and summary, but it does not mention result ordering, matching behavior, limits, or other operational traits beyond what annotations cover.

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

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

The description is a single front-loaded sentence with no redundant or filler content. Every phrase contributes to identifying the operation, resource, scope, and search 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?

Given the simple one-parameter schema, existing output schema, and rich annotations, the description provides enough context to understand what the tool does and what the query targets. It could be stronger with alternatives or matching rules, but it is largely complete for this tool's complexity.

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

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

Schema description coverage is 0%, so the schema does not explain the single 'query' parameter. The description compensates partially by indicating that the query is matched against document names and summaries. It does not specify matching syntax, case sensitivity, or other query semantics, so it is adequate but incomplete.

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: 'Search accessible Docmino documents.' It adds that search applies to name and summary, making the operation clear. It does not explicitly distinguish this tool from siblings such as list_documents, get_document, or fetch, 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?

The word 'Search' and the fields 'name and summary' imply the tool's intended use for keyword lookup, rather than listing or fetching a specific document. However, there is no explicit guidance about when to use this versus list_documents, get_document, or fetch, and no exclusions or 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 destructiveHint=true and idempotentHint=true, but the description adds important beyond-schema behavior: expectedRevision is used for conflict detection, omitted existing pages are deleted, and deletion requires permission. These are specific operational consequences an agent needs before invoking a destructive update.

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 three sentences, front-loads the core update action and conflict detection, then immediately states the destructive page-deletion rule and guide reference. There is no redundant restatement and every sentence adds useful information.

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

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

The tool has 8 parameters, nested page objects, destructive behavior, and an output schema. The description covers the critical risky behaviors: conflict detection, deletion of omitted pages, deletion permission, and where to find authoring syntax. It does not explain summary or give page-tree shape guidance, but the output schema and get_authoring_guide reference reduce the remaining gap.

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

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

Schema description coverage is only 25%, so the description must compensate. It clarifies expectedRevision's conflict-detection role and the destructive semantics of omitting pages, but it does not explain summary or the page object structure in detail. It partially compensates for the low schema coverage rather than fully resolving 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 a specific verb and resource: updating MDX document content and the authoritative page tree. It also adds scope through expectedRevision conflict detection and page deletion behavior. It does not explicitly differentiate itself from siblings such as create_document or update_project, so a 4 is appropriate.

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 this is for modifying an existing document and points to get_authoring_guide for supported interactive component syntax. However, it does not state when to use this tool versus create_document, update_project, or other sibling tools, and provides no explicit exclusions.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds only that three specific fields are updatable, and says nothing about whether omitted fields are preserved or cleared, which is exactly the risk an agent needs to know for a destructive update.

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

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

A single front-loaded sentence with no filler, which is appropriate in size. Brevity costs it here only because the size is too small for a destructive four-parameter mutation.

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

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

An output schema and rich annotations reduce what must be explained, but for a destructive, idempotent update with 0% param coverage the missing pieces (required id, partial-update behavior) are exactly what an agent needs to call it safely.

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

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

Schema description coverage is 0%, so the description carries full burden, yet it only restates the field names already visible in the schema. It never explains that id is the required selector and non-updatable, nor the partial-update semantics of name/description/instructions.

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 ("Update a project") plus the exact fields it touches, so the agent knows this mutates an existing project rather than creating one. It does not distinguish itself from update_document or create_project, but the resource noun makes the target 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?

No guidance on when to use this instead of update_document or other siblings, and no note that the project must already exist or that only some fields may be supplied. The agent is left to infer all invocation conditions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows this is a destructive, repeatable mutation. The description adds no behavioral context beyond the basic mutation itself: it does not explain what access may be lost when a role is downgraded, what permissions are required, or what side effects occur. With annotations covering the safety profile, this is a minimal addition.

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

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

The definition is a single front-loaded sentence with no wasted words. Its terseness is efficient, though it comes at the cost of the missing details noted in other dimensions.

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 output schema covers return values, but this is a destructive mutation with an entirely undocumented 'id' parameter and no explanation of permission requirements or access-change effects. For a two-parameter destructive update with 0% schema coverage, the description is not complete enough to guide correct invocation 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 description coverage is 0%, so the description must compensate for two undocumented parameters. It references 'role' generically but does not explain the 'id' parameter, the accepted role values, or any constraints, leaving the schema to carry meaning it does not actually provide.

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

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

The description states a specific verb and resource: 'Change' an existing access grant's 'role'. This clearly distinguishes it from sibling operations like invite_share and remove_share by implying modification of an existing grant rather than creation or deletion. It does not explicitly name those siblings, so it falls short of a 5.

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

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

Usage is implied: use this when an existing share's role needs to change. However, there is no explicit when-not guidance, no mention of prerequisites such as admin permissions, and no direct comparison to invite_share or remove_share for disambiguation.

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