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

With no annotations provided, the description carries the full burden of behavioral disclosure. It covers the API key permission requirement, scope visibility, the ownership restriction on SHARED scope, and required parameter relationships. This is meaningful behavioral context beyond what the schema alone offers, though it does not describe the response shape or error 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?

The description is two dense sentences with no filler. The primary action is front-loaded, followed by prerequisites and conditional rules. Every clause contributes either a required behavior, a dependency, or a scope constraint, making the structure efficient and highly scannable.

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 7-parameter tool with no output schema and no annotations, the description covers the critical operational context: auth, parameter combinations, scope behavior, and ownership restrictions. It does not mention docCode explicitly, but that parameter is required by the schema and self-evident. Minor gaps like return value and exact error conditions prevent a 5.

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 86%, so the baseline is 3. The description adds valuable cross-parameter semantics: content vs color-only behavior, quotedContent being required for highlights, and scope visibility nuances. These relationships are not inferable from individual parameter descriptions, so the description clearly enhances parameter understanding.

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

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

The description opens with a specific verb and resource: 'Attach a note or highlight to a document.' This clearly distinguishes the tool from siblings like postmd_delete_note, postmd_update_note, and postmd_list_notes, which cover delete, update, and list operations respectively. It is unambiguous what action this tool performs.

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

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

The description provides concrete usage guidance: give content for a note, give color alone for a colour-only highlight, and require quotedContent in that case. It also explains the scope options and their visibility implications. It does not explicitly name sibling tools as alternatives or state when not to use this tool, so it falls just short of a 5.

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

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

With no annotations, the description carries the full behavioral burden and performs well: it discloses that no API key is needed, that an optional key grants ownership/update ability, that groupId requires a specific permission, and that the tool returns docCode and data.shareUrl. It does not cover idempotency or public-visibility details, but for a create/publish tool this is strong behavioral context.

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

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

Three dense sentences with no filler: purpose, return values and how to distribute them, then optional ownership/group behavior. The most important distinction ('No API key required') is front-loaded, and every sentence contributes real 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?

Even though there is no output schema, the description names the key return fields (docCode and data.shareUrl), which is the most important missing output information. It also covers anonymous vs. API-key ownership and group permission. It could be more complete by explicitly addressing how anonymous documents behave or by routing to file-based sibling tools, but the high schema coverage fills most remaining gaps.

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 seven parameters. The description adds a bit of context for groupId by connecting it to the default group and documents:write, but it does not add meaning for title, fileName, password, viewerStyle, or shareEndDate beyond what the schema provides.

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

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

The first sentence states a specific action and resource: 'Publish Markdown as a PostMD web page,' which is clear and not a tautology. It does not explicitly differentiate from sibling tools like postmd_create_document_from_file, but the required 'markdown' parameter and publish/web-page framing make the core purpose unambiguous.

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

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

The description provides actionable context: no API key is required for anonymous publishing, while providing an API key makes the document owned and updatable later, and groupId files into a specific group with documents:write. It does not explicitly name sibling alternatives or say when to prefer the file-based create tools, so it lacks direct when-not-to-use 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds important context that the file is read from the machine running the MCP server and that this is intended for large files. However, it does not disclose side effects, authentication needs, or what the tool returns after creating 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?

The description is one sentence with no filler. It front-loads the key behavioral distinction and use case, making it easy for an agent to quickly grasp when to invoke this 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?

The description provides the critical server-local file context and the large-file use case, which is helpful. However, it relies on the sibling tool for the actual meaning of 'same as postmd_create_document,' and with no output schema or annotations, it leaves return behavior and side effects unexplained.

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

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

The input schema has 100% parameter coverage with detailed descriptions for all 7 parameters, so the schema already carries the semantic load. The description adds little beyond the motivation for using filePath instead of a pasted body, which does not significantly enhance parameter understanding.

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

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

The description clearly identifies this as the file-based variant of postmd_create_document and specifies that it reads Markdown from filePath on the server machine. It distinguishes itself from the sibling tool by targeting large files instead of pasted bodies, though it does not fully describe the creation action on its own.

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

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

The description explicitly says to use this tool 'for large files instead of pasting the body,' giving clear context for when it is preferred over the sibling postmd_create_document. It also implies the file must be present on the MCP server, but it does not explicitly state 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?

With no annotations, the description carries the full burden, and it discloses a critical behavior: the outer resultCode is 200 even when individual files fail, directing the agent to inspect data.succeeded and data.results. It also mentions the API key requirement. This goes well beyond the schema.

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

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

The description is extremely compact: two sentences convey the core operation, the auth requirement, and the surprising partial-failure behavior. No words are wasted and the most important caveat is front-loaded.

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

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

Without annotations or an output schema, the description explains the essential non-obvious behavior (partial failures and where to find per-file results). It could add a bit more about the success response format or when a fully successful call looks like, but it is sufficient for an agent to invoke the tool and interpret the returned data.

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 each parameter is already documented. The description does not add parameter-level detail beyond what the schema provides, which is acceptable given the high coverage.

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

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

The description states a specific verb ('Publish'), a specific resource ('.md files'), and the scope ('several in one call / bulk upload'). It also distinguishes itself from the sibling postmd_create_document_from_file, which handles a single file.

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

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

The phrase 'Publish several .md files in one call (bulk upload)' clearly implies the tool is for multi-file publishing, distinguishing it from single-file sibling tools. It also states the required permission (documents:write). It does not explicitly enumerate when not to use it, but the 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?

With no annotations, the description carries the behavioral burden. It discloses the auth requirement (groups:write) and hints at downstream capabilities, but it does not describe the response, side effects, uniqueness rules, or error behavior for a mutation 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?

The description is two short sentences with no filler. The core action is front-loaded, followed by the auth prerequisite and a brief explanation of the group's purpose. Every sentence earns its place.

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

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

The description is adequate for a simple create operation: it states the purpose and auth requirement, and the schema covers the optional expireDate. However, with no output schema and no annotations, it omits what the client receives on success and any error or validation behavior.

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

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

The description adds no parameter-level meaning. The schema covers only expireDate; the required name parameter has no schema description and the tool description does not compensate by explaining it. The name is somewhat obvious, but overall the description does not enrich the parameter semantics.

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

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

The description states the action and resource precisely: 'Create a group.' This clearly distinguishes it from sibling tools that create documents or update/delete groups, and there is no ambiguity about what the operation does.

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

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

The description gives clear context for when to use the tool: it is for creating a group that will later hold documents and have members invited through the web app. It also names the required API key permission, though it does not explicitly say when not to use it or mention alternatives.

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

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

With no annotations, the description carries the full burden and explains key behavioral traits: deletion is recoverable for 30 days before permanent purge, and an API key with documents:write is required. It does not mention idempotency or the outcome for non-existent documents, but for a single-parameter delete operation this is useful and goes beyond a bare 'Delete a document' statement.

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 contain all necessary information: the operation, the ownership constraint, the recovery window, and the required permission. It is front-loaded with the verb and resource and contains 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?

For a tool with one string parameter and no output schema, the description covers the main operational context: what is deleted, who may delete it, the retention period, and the required API permission. It is not fully complete because it omits what happens after deletion, such as the success response or error behavior, but this is a minor gap.

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

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

The input schema merely defines docCode as a string with no description, and the description does not explain docCode, its format, or how to obtain it. With schema coverage at 0%, the description fails to compensate, though the parameter name is reasonably self-explanatory as a document identifier.

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

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

The description clearly states the action 'Delete', the resource 'a document', and the ownership constraint 'you own'. This distinguishes it from sibling tools like postmd_delete_note (deletes a note) and postmd_update_document (modifies rather than deletes). The verb-resource pair is specific and unambiguous.

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

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

The phrase 'a document you own' implies the tool is intended for owned documents only, but it does not explicitly state when to use it over alternatives such as postmd_delete_note or postmd_update_document. There is no mention of what to do when the document is not owned or when a different operation is appropriate. This leaves usage context largely implicit.

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 discloses the destructive action, owner restriction, default-group protection, the side effect that documents are not deleted, and the required API permission. It could additionally state irreversibility or where the documents go, but the key behavioral traits are clearly communicated.

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

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

Three short sentences, each carrying distinct useful information: the action, ownership and default-group constraints, and the document side effect. There is no filler or repetition.

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

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

For a single-parameter destructive tool with no annotations and no output schema, the description covers permissions, restrictions, and the most important side effect. It does not specify what successful deletion returns or where undeleted documents end up, but these are minor given the tool's simplicity.

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 required parameter groupId is not mentioned in the description, and schema description coverage is 0%, so the description does not compensate for the schema gap. The agent must infer from the parameter name and tool name that groupId identifies the group to delete. This is the weakest dimension because even a brief mention of 'identifies the group to delete' would have sufficed.

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 begins 'Delete a group', which is a specific verb plus resource. It also clarifies important scope restrictions (owner only, default group cannot be deleted), distinguishing this from sibling document and note deletion tools. The intended action is unmistakable.

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

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

The description gives clear contexts for safe usage: it can be used to delete a group, but not the default group, and only by the owner with groups:write permission. It does not explicitly name alternative tools, but the sibling list makes the resource distinction clear. The exclusion of the default group serves as an effective when-not condition.

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 must carry the behavioral disclosure. It mentions the required permission and the ownership restriction, which is helpful. However, it does not state that deletion is permanent, what happens to shared notes, or any confirmation behavior. For a destructive tool this is a partial 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?

A single sentence with no filler. The main action and scope are front-loaded, and the permission requirement is included without unnecessary explanation.

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

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

The description covers core purpose and permissions but lacks explicit parameter definitions and any mention of the return value or success/failure behavior. For a simple two-parameter delete operation, this is a moderate gap that an agent may need to infer from sibling note tools.

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

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

The schema provides no descriptions for docCode or noteId, and the description never references these parameters directly. The property names are somewhat self-explanatory, and the ownership context implies a document-note relationship, but the agent gets no explicit parameter-level guidance.

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

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

The description clearly states the verb ('Delete') and the resource ('a note'), and adds specific scope: your own note or a shared note on a document you own. This makes it easy to distinguish from note-related siblings like add, update, or resolve.

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 explicit conditions for when deletion is allowed, including ownership requirements and the required documents:write permission. Since there is no alternative delete-note sibling, no additional routing between deletion tools is needed.

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

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

Annotations already declare readOnlyHint=true, so the description is not solely responsible for safety disclosure. It adds meaningful behavioral context: the tool returns only metadata, omits content, and requires no authentication. No contradiction with annotations.

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

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

Two compact sentences deliver the key facts first: what is returned, what is excluded, and which sibling to use instead. Every sentence earns its place with no filler or repetition.

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

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

For a simple one-parameter metadata fetch with no output schema, the description sufficiently explains the return scope, lists the returned fields, and routes to the raw-content counterpart. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100% and docCode already has a clear description with an example. The description only repeats that lookup is by docCode without adding new meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Get document metadata by docCode', then enumerates the exact fields returned. Explicitly distinguishes itself from postmd_get_document_raw by noting content is excluded, so an agent can immediately tell the two tools apart.

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?

Directs the agent to postmd_get_document_raw when Markdown source is needed, which is a clear alternative and selection condition. Also discloses that no API key is needed, giving concrete usage context without requiring the agent to infer prerequisites.

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

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

Annotations already mark this as readOnlyHint=true; the description adds non-obvious behavioral constraints: no API key required, conditional password handling, and the expired-document failure case. These are important for an agent to know before invoking.

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, front-loaded sentences with no filler. Every sentence adds necessary context: what is returned, authentication expectations, and access constraints.

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

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

For a simple read-only tool with two parameters, the description covers purpose, access, and failure conditions sufficiently. It could be slightly more complete by explicitly distinguishing itself from postmd_get_document, but that gap is minor.

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 documents password but not docCode, and the description reinforces the conditional need for password while implying docCode identifies the document. It does not define docCode's format or origin, so the parameter guidance 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?

States the exact action and resource: 'Get the stored Markdown source of a document.' The word 'raw' and the focus on Markdown source clearly separate this from the sibling postmd_get_document, which likely returns a processed or rendered form.

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

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

Provides clear operational context: the tool is public with no API key, password-protected documents require the password parameter, and expired documents cannot be read. It does not explicitly name an alternative or say when not to use it, so it stops short of a 5.

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

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

The readOnlyHint annotation already covers safety, and the description adds valuable behavioral context: pagination, substring searching on title/file name, and case-insensitivity. It also discloses the required permissions, which helps the agent anticipate auth failures.

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 deliver the core purpose, auth requirement, and key behavioral details with no filler. The most important information is front-loaded, and every sentence earns its place.

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

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

Given a 7-parameter tool with no output schema, the description covers the essentials: purpose, required permissions, pagination, and query semantics. It does not describe the response shape or default page size, but the parameter schema and readOnly annotation cover much of the remaining context.

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 description adds meaning for q by clarifying it is a substring, case-insensitive search, and 'Paged' gives context for page/size. However, the schema already documents q, sort, folderId, and rootOnly, and the description does not explain defaults or the relationship between folderId and rootOnly beyond what the schema provides.

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

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

The description states a specific verb and resource: 'List documents in a group.' This clearly distinguishes it from sibling tools like postmd_list_groups (which lists groups) and postmd_list_my_notes (which lists notes). The group scope is explicit and immediately understandable.

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

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

The description implies the tool is used when you need documents belonging to a group, and it usefully states prerequisite API key scopes (groups:read and documents:read). However, it does not explicitly contrast with alternative list tools or mention when not to use it, leaving some selection inference to the agent.

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

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

Annotations already declare readOnlyHint=true. The description adds useful behavioral context beyond that: it requires a specific API key scope (groups:read) and states that results are paged. This helps the agent understand prerequisites and response behavior without contradicting the read-only annotation.

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

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

The description is two short sentences with no filler. It front-loads the core action, then efficiently adds the auth requirement and paging behavior. Every word earns its place.

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

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

For a simple read-only list tool with no required parameters and full schema coverage, the description covers the essential operational context: purpose, permission requirement, and pagination. It does not specify pagination defaults or page-size limits, but those are not necessary for basic invocation.

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

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

Schema description coverage is 100%, with clear descriptions for both optional parameters ('1-based page number' and 'Items per page'). The description adds only the general 'Paged' behavior, which does not meaningfully expand on what the schema already provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb and resource ('List groups') and further scopes it to 'the key's member belongs to,' making it clear this is about the authenticated member's group memberships. This distinguishes it from siblings like list_group_documents (documents in a group) and list_my_notes (notes), even without naming them.

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

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

The description provides clear context: it lists groups for the API key's member, requires groups:read permission, and is paged. It does not explicitly state when not to use it or name alternatives, but the purpose and auth requirement make the intended usage 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 provide readOnlyHint=true, and the description adds meaningful behavioral context: it requires documents:read, filters to the member's own notes, and returns docCode/documentTitle alongside each note. This goes beyond the annotation without contradicting it.

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

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

The description is a single, focused sentence that front-loads the core behavior and includes only necessary constraints and output details. Every clause earns its place; there is no redundancy or vague 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?

For a parameterless, read-only list tool, the description is complete: it identifies the resource, the ownership filter, the required permission, and the accompanying output fields. No output schema exists, but the description compensates by naming the returned fields.

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

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

The tool has zero parameters and schema coverage is 100%, so there are no parameter semantics to clarify. The description still adds value by explaining what the response conceptually contains, which is sufficient for a parameterless tool.

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 ('List') and a specific resource ('every note the key's member wrote, across all documents'), and it names the output fields (docCode, documentTitle). This clearly distinguishes it from the sibling postmd_list_notes by adding the ownership scope ('the key's member wrote').

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 a clear use context — listing notes authored by the authenticated key's member — and states the required permission (documents:read). It doesn't explicitly name when to use postmd_list_notes instead, but the scope distinction is strong enough to guide an agent.

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

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

Even though readOnlyHint already signals safety, the description adds meaningful behavioral detail: result ordering, that each note has mine/manageable flags to trust rather than re-derive permissions, auth requirements, and password handling. It complements rather than contradicts the annotation.

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 dense sentences with no filler: scope, ordering, auth, flag guidance, and password condition all earn their place. Critical constraints are front-loaded.

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

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

For a 2-parameter, read-only list call the description is largely complete: it states scope, order, auth, password behavior, and the key returned flags. Without an output schema it could be stronger on the exact note payload structure, but the essential context for invoking correctly is present.

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

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

Schema coverage is 50%, with password described in the schema and echoed in the description. The required docCode parameter has no schema description and is not clarified beyond 'on a document', leaving some ambiguity about what a valid code looks like.

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

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

The description opens with a specific verb and object — 'List notes and highlights on a document' — and precisely qualifies scope: 'your own plus every SHARED one, newest first.' This makes it easy to distinguish from the sibling postmd_list_my_notes without reading schemas.

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

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

It gives clear context: the tool covers own plus shared notes, requires a documents:read API key, and needs a password for protected documents. It does not explicitly tell the agent to use postmd_list_my_notes when only own notes are wanted, so it falls just short of a perfect score.

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 it does so well. It discloses the replacement side effect ('this replaces its current group'), ownership and group-use constraints, and the required API key scope. This gives an agent a realistic picture of the operation's conditions and consequences.

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 with no filler. The key action is first, the one-group replacement behavior is front-loaded, and the auth requirement is stated at the end. Every sentence adds necessary 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 moderate-complexity move operation with no annotations and no output schema, the description covers the action, preconditions, side effects, and auth. It does not describe return values or failure behavior, but nothing essential to invoking the tool correctly appears to be missing.

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

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

Schema description coverage is only 33%, so the description must compensate. It maps docCode to 'a document you own' and groupId to 'a group you can use,' adding meaning beyond the bare parameter names. folderId is already described in the schema as 'File it into this folder of that group.' It does not restate types, which the schema already provides.

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

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

The description uses a specific verb ('Move') on a clear resource ('a document') with an explicit destination ('into a group... optionally into a folder'). It also clarifies the crucial semantic that a document belongs to exactly one group, which differentiates this move operation from content updates like postmd_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 clearly implies when to use this tool: when you need to change the group membership of a document you own. It also adds preconditions (document ownership, group usability, documents:write permission). It does not explicitly name alternatives or say 'use update_document for content changes instead,' but the semantics are clear enough.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It covers reversibility (resolved=false reopens), permission requirements, and shared-note scope. It does not fully specify what happens on non-shared notes or describe the response, but these are minor gaps for a toggle 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?

Three short sentences that front-load the core operation, then add scope and auth context. Every sentence earns its place and there is 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?

For a simple toggle with three required parameters and no output schema, the description provides the essential operation, undo path, applicable note type, and authentication requirement. It is nearly complete, but the undocumented docCode/noteId parameters keep it from a perfect score.

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?

Only one of three required parameters (resolved) gets any semantic explanation, and that mostly repeats the schema description. docCode and noteId are left entirely to their names, despite schema coverage being only 33%; the description does not compensate for the missing definitions.

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

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

The description names a specific action ('Mark a note as settled'), the resource ('a note'), and the key behavior (resolved=false reopens it). This clearly distinguishes it from note CRUD siblings like postmd_update_note or postmd_delete_note.

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 states the relevant context ('Meaningful on SHARED notes') and the permission boundary (author or document owner may set it; requires documents:write). It does not name a specific sibling to use instead, but the scope and authorization are explicit enough to guide 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?

With no annotations, the description carries the full behavioral burden, and it does disclose the key write behaviors: markdown replaces stored content, metadata fields replace only that field, and clear flags remove the password/end date. It also states the required write permission. It falls short of 5 because it does not describe return values or conflict behavior such as password plus clearPassword together.

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

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

The description is two carefully written sentences with no filler. The first sentence covers purpose and auth, and the second covers all important update/removal semantics, front-loading the most critical 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 9 parameters, no annotations, and no output schema, so the description must cover more ground. It handles auth, ownership, replacement, and removal semantics well, but it omits return-value information, the file-upload alternative, and conflict handling between password and clearPassword. These are gaps an agent would need to resolve from sibling tools or runtime behavior.

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

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

The schema already documents 7 of 9 parameters, so the baseline is 3. The description adds useful cross-field semantics: 'any metadata field replaces that field' and clear flags remove values rather than set them, which is not captured by the property descriptions alone.

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: 'Update a document you own,' with an ownership constraint that helps scope the tool. It also explains that markdown replaces stored content and metadata fields replace individual fields. It does not explicitly contrast itself with postmd_update_document_from_file, so sibling differentiation is only implicit.

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

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

The description gives a clear precondition: 'Requires an API key with documents:write.' It also explains when to use markdown, metadata fields, and the clear flags, which gives an agent solid context for calling the tool. It does not name alternatives or state when not to use this tool, so exclusions are missing.

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 exist, so the description must carry the behavioral burden. It adds one useful fact (the file is read on the MCP server host, not the client), but it never states that this is a mutating/overwriting operation, what permissions are required, or what side effects occur. The 'Same as postmd_update_document' reference is implicit, not a substitute for explicit 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?

One sentence with no filler; the key selection fact (server-local filePath variant of postmd_update_document) is front-loaded.

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

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

The schema carries most parameter meaning, and naming the sibling links to the broader behavior, but a 9-parameter mutation tool with no annotations and no output schema needs at least one sentence on overwrite/permissions/result. The definition is enough for selecting the tool but not fully enough for invoking it safely without opening the sibling description.

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 high (78%) and the individual parameter descriptions already document filePath, fileName defaulting, viewerStyle fallback, date formats, and clear booleans. The description reinforces that filePath is the Markdown source but adds little beyond the schema. Baseline 3 is appropriate.

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

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

Names the sibling tool and frames itself as the same operation with a file-based content source, which distinguishes it from postmd_update_document. It stops short of being fully self-contained because the core 'update a document' semantics are inherited from that sibling rather than stated directly.

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?

Identifies postmd_update_document as the alternative and explains the decision criterion: content is read from a server-local filePath instead of passed inline. It doesn't spell out exact scenarios or exclusions, but the selection cue 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?

With no annotations, the description carries the behavioral disclosure burden and does so reasonably well: it identifies the operation as an update, documents the ownership and API-key requirement, and explains that clearExpireDate removes the expiry date. It does not mention combined-field semantics or irreversibility, but the core behavior is transparent enough for a small update tool.

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

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

The description is four short sentences with no filler. The primary action is front-loaded, followed by owner/permission requirements and the non-obvious clearExpireDate behavior. 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?

For a low-complexity update tool with no output schema and no annotations, the description covers the essential call context: what the tool does, who may use it, what permission is required, and the special clear-expiry behavior. The main gap is the lack of explicit statement about whether the update fields can be combined or how conflicts between expireDate and clearExpireDate are resolved, but this is not severe given the tool's simplicity.

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

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

Schema description coverage is only 50%, and the description partially compensates by mapping 'Rename' to the name parameter and 'change its expiry' to expireDate. However, groupId is left without explicit explanation, and the description does not clarify whether name, expireDate, and clearExpireDate can be used together or whether omitted fields remain unchanged. This is adequate but not complete.

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

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

The description states a specific action and resource: 'Rename a group or change its expiry.' This clearly distinguishes the tool from create/delete/list group siblings and from document update tools. It also mentions the 'clearExpireDate' behavior, so the agent knows both primary update modes.

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 clear context by specifying 'Owner only' and 'Requires an API key with groups:write,' which helps the agent determine when this tool is appropriate. It does not explicitly name alternatives or state when not to use it, but the sibling set makes the update-vs-create/delete distinction reasonably obvious.

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 supplied, the description carries the behavioral disclosure burden. It does disclose the auth requirement ('Requires an API key with documents:write'), the scope omission behavior, and an invariant ('The note must keep text or a colour'). However, it does not disclose what happens to omitted fields like content or quotedContent, whether the update is a merge or overwrite, or what error/response behavior looks like.

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 only three sentences and front-loads the core purpose. It includes useful operational details without filler. The final sentence is somewhat ambiguous but still concise and purposeful.

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 six parameters, no output schema, and no annotations, this description is incomplete for correctly invoking the tool. An agent still lacks needed semantics for required identifiers (docCode, noteId) and for content/quotedContent, and no return or error behavior is described. The included auth and scope details are helpful but not 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 low at 33%; only color and scope have schema descriptions. The description does not explain docCode, noteId, content, or quotedContent, which are all undocumented in the schema. It adds only a vague constraint about text or colour, and it restates the scope omission behavior already present in the schema, so it fails to compensate for the parameter documentation 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 states a specific verb and resource: 'Edit a note you wrote.' It also adds an ownership/scope qualifier ('you wrote') that helps distinguish this from sibling tools like postmd_add_note, postmd_delete_note, or postmd_update_document. The core purpose is immediately identifiable.

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

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

The description implies usage through 'Edit a note you wrote,' but it does not explicitly contrast with alternatives such as postmd_add_note, postmd_delete_note, or postmd_update_document. It does provide a prerequisite (API key with documents:write) and a scoping behavior, but not clear when-to-use versus sibling tools.

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

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

With no annotations, the description carries the behavioral disclosure burden. It discloses the required auth scope, allowed file types, and the returned data.url usage. It does not mention limits like file size or overwrite behavior, but the main side effects and prerequisites are covered.

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

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

Three concise sentences front-load the purpose, then give the requirement, allowed types, and the next step. There is no filler or redundant restatement of the schema.

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

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

For a two-parameter upload tool with no annotations and no output schema, the description is strong: it covers auth, accepted types, how to use the response URL, and the logical next tool call. Nothing essential for a correct invocation is missing.

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

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

The input schema already documents both parameters: filePath (path on the MCP server host, absolute preferred) and fileName (defaults to basename of filePath). The description adds the allowed-file-types constraint but does not add significant parameter-specific meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The opening sentence uses a specific verb ('Upload') with a clear resource ('an image or PDF') and purpose ('to reference from a document'). This distinguishes it from the sibling create/update tools, none of which target attachments.

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 clear when-to-use context: uploading an image or PDF to be referenced from a Markdown document. It also states the prerequisite API key scope and the follow-up workflow using postmd_create_document, though it does not explicitly discuss when not to use this tool.

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