postmd-mcp-server

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

Annotations carry almost nothing (only destructiveHint=false), so the description does the heavy lifting and does it well: 30-day retention extending on each read, that passwordless documents can be updated/deleted by anyone, that password-protected ones need the password or owner API key, and the documents:write scope requirement. These are consequential side effects an agent must know before publishing.

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?

Purpose is front-loaded in the first sentence, and the remaining sentences each carry distinct operational facts (return fields, retention, permissions, docCode convention). It is dense and somewhat long, but nearly every clause earns its place.

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

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

With no output schema, the description correctly supplies the return contract (docCode, data.shareUrl, data.retainedUntil) and explains retention, ownership, and the docCode-in-source-file convention. An agent has everything needed to publish and later re-locate the document.

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

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

Schema coverage is 100%, so the baseline is 3 — each parameter is already documented in the schema, including title defaults, fileName extension requirement, password behavior, and viewerStyle fallback. The description mostly reinforces permission semantics already present in the schema (groupId needs an API key) rather than adding new parameter-level 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 — 'Publish Markdown as a PostMD web page' — which is unambiguous and cleanly separable from the sibling get/update/delete operations. An agent can identify the create action without opening the schema.

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

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

Gives clear conditions: no API key needed for anonymous publishing, API key makes the document belong to a member, and groupId files it into a group (needing documents:write). It stops short of explicitly naming alternatives such as postmd_update_document for later edits, but the auth/no-auth and ownership branches give strong 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 destructiveHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing the authorization model: password-protected docs need the password or owner's API key, while unprotected docs can be deleted by anyone. That is a meaningful behavioral trait not captured by 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?

Two sentences, no filler, with the core action front-loaded and the authorization rule following immediately. Every clause earns its place.

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

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

For a simple two-parameter destructive tool with no output schema, the description covers the action and the authorization prerequisite well. It could note irreversibility or the outcome of a successful delete, but the essential information an agent needs to call it 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% — docCode has no description, but the description explains the semantics of the password parameter (required only when the document is protected and you aren't the owner), reinforcing and slightly extending the schema's own note. The description compensates for the undocumented docCode by making the overall invocation model clear.

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+resource ('Delete a document'), which is unambiguous and clearly distinct from the create/get/update siblings. It doesn't explicitly name a sibling to contrast with, but the destructive 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?

It states the authorization condition for password-protected documents versus unprotected ones, which is useful context for invoking the tool. However, it offers no guidance on when to prefer this over siblings or what preconditions exist (e.g., whether deletion is reversible), so usage is implied rather than fully framed.

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 provide readOnlyHint=true, and the description adds useful behavior beyond that: no API key required and a negative scope ('content is not included'). It does not cover pagination (not applicable for a single-doc lookup), so a 4 is fair.

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

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

Three tight clauses: what it returns, auth posture, and the sibling escape hatch. Zero waste and the resource and key field 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?

With no output schema, the description enumerates the returned fields (title, fileName, hasPassword, viewerStyle, timestamps), states the auth model, and points to the sibling for content — everything an agent needs to call it correctly.

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

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

Schema coverage is 100% and docCode already has an example (P-123-456-789) in the schema. The description only restates that lookup is by docCode, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get document metadata by docCode') and enumerates the returned fields, so the agent knows exactly what it retrieves. It also explicitly distinguishes itself from the sibling postmd_get_document_raw.

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

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

Explicitly says content is not included and names the alternative (postmd_get_document_raw) for Markdown source, giving the exact condition that routes to the sibling. Also clarifies it is a public endpoint requiring no API key.

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 safety is covered; the description adds genuinely useful behavioral context beyond that — no authentication required and a conditional password requirement. Error or failure behavior (e.g. wrong password, missing doc) is not described, keeping it below a 5.

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

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

Three short sentences with zero filler: purpose first, then access model, then the conditional parameter note. Every sentence carries information an agent needs before calling.

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?

There is no output schema, but the description effectively characterizes the return value as the document's stored Markdown source, which is sufficient. The one remaining gap is docCode's semantics, which neither the schema nor the description covers.

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%: the password parameter is described in the schema, but docCode has no description anywhere. The description reinforces the conditional semantics of password ('password-protected documents need password'), which is real added value, but it does nothing to explain docCode's format or source.

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: retrieve the stored Markdown source of a document. The word 'raw'/'Markdown source' implicitly separates it from the sibling postmd_get_document, but that distinction is never made explicit, so an agent must infer it.

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

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

Gives clear operational context: the endpoint is public with no API key, and a password is required only when the document is password-protected. It stops short of naming a preferred alternative (e.g. postmd_get_document for rendered content), so the when-not-to-use case is left 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?

With only destructiveHint=true in annotations, the description carries most of the burden and does well: it discloses the authorization model, that clearPassword removes protection, and that replacing content requires notesOnReplace. It does not explain the return payload or whether updates are atomic/reversible, but the destructive side effects of replacement are surfaced.

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?

Four short sentences, front-loaded with the action, then auth rules, then the two mutating behaviors. No filler; the only cost is that it reads as a compact rule list rather than a narrative.

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 9-parameter destructive mutation with no output schema, the description covers the critical unknowns: authentication, content-vs-metadata replacement, and the notesOnReplace requirement. Minor gaps remain (e.g., behavior of unknown title/fileName combinations, confirmation of success), but nothing essential is missing.

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

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

Schema description coverage is 78%, so the schema already documents most parameters (including the detailed notesOnReplace semantics). The description restates markdown/metadata/clearPassword behavior at a high level, adding cohesion but little information beyond the schema.

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

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

The opening 'Update a document' gives a clear verb+resource, and the following sentences specify what updating entails (content replacement vs. metadata field replacement, password clearing). It does not explicitly contrast itself with the create/delete/get siblings, but the operation is unambiguous.

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

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

It states the auth conditions (password or owner API key for protected documents; open for unprotected) and that metadata fields replace individually, which implies when to use each mode. However there is no explicit 'use X instead when Y' guidance and no mention of the sibling tools, so alternatives are left to inference.

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