dochost-mcp

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

The description adds rich behavioral details beyond the annotations: permanence, immediate effect, slug being freed, and safe no-op for already-deleted pages. These specifics are not covered by readOnlyHint=false or destructiveHint=true, significantly enhancing transparency.

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 concise sentences, front-loaded with the core action. Each sentence provides useful information: what it does, immediate effects, and idempotency, with no wasted words.

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

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

For a simple one-parameter delete tool, the description covers the purpose, parameter semantics, behavioral outcomes, and safety (no-op). Annotations cover destructive nature, and an output schema exists, making this complete.

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?

With schema description coverage at 0%, the description compensates by explaining that the 'slug' parameter is the page identifier used for deletion. It doesn't repeat schema constraints but adds semantic meaning that the schema alone doesn't convey.

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 tool deletes a page permanently by slug, which is a specific verb and resource. It also distinguishes from sibling tools like get_page, list_my_pages, publish, and update_page by focusing on 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?

The description implies usage for deleting pages but does not explicitly state when to use it versus alternatives. It provides behavioral context about effects (immediate link stop, slug freed, no-op) but lacks explicit when-to-use or 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to cover safety. It adds context about the specific data returned (plan, quota, entitlement flags), which goes beyond the annotations. 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?

The description is a single, tightly written sentence that front-loads the core function and ends with a practical usage tip. No redundant words or 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 read-only account info tool with no parameters and an output schema, the description fully covers what the tool does, when to use it, and what to expect. It is complete and actionable.

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 the schema is empty (100% coverage). The description adds meaning by listing the types of information returned, which helps set expectations. Even though there are no parameters to explain, this context is valuable, earning a baseline-plus score.

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 'Get your plan, page-quota usage, and entitlement flags', specifying the exact resource and data returned. It distinguishes itself from siblings like get_page and list_my_pages by focusing on account-level information rather than page-level details.

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 an explicit use case: 'Call before publishing so you know your limits up front.' It implies when to use this tool over alternatives, but does not explicitly name alternatives or mention when not to use it, so it falls 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable behavioral disclosure: 'Never returns the page body or the password.' This is an explicit constraint on the response beyond the annotation, which helps the agent set expectations. No contradictions 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?

The description is a single, front-loaded sentence. It states the action, resource, identifier, returned fields, and a critical negative guarantee ('Never returns the page body or the password') without any redundant wording. 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?

The tool is simple: one parameter, output schema exists, and annotations cover safety. The description fully covers what the agent needs to know: what data is returned and what is excluded. With an output schema present, it doesn't need to list return types. No significant gaps remain.

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 does by explicitly stating the tool fetches pages 'by slug', clarifying the purpose of the single parameter. The schema provides type and length constraints. The description adds the semantic role of the slug, which is sufficient for this simple one-parameter tool, though it doesn't elaborate on slug format or sourcing.

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 ('Get') and resource ('your pages by slug'), enumerates the returned fields (title, format, status, counts, expiry, password-protection), and clearly distinguishes itself from siblings like list_my_pages (listing) and delete_page/update_page (mutations). It also explicitly states what it does NOT return, which sharpens purpose.

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 metadata for a single page identified by slug. It does not explicitly name alternatives or exclusions (e.g., 'use list_my_pages to list all pages'), but the context from sibling tool names and the 'by slug' qualifier provides clear usage context. Lacks explicit when-not-to-use guidance, so not 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?

Annotations already declare read-only and non-destructive. The description adds behavioral traits beyond that: pagination, order (newest first), and the fact that records are compact without bodies. This informs the agent about response characteristics without contradicting 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?

The description is a single, well-structured sentence. It leads with the action and resource, then adds ordering and pagination details, with no filler words.

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

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

With the output schema present and annotations covering safety, the description needn't explain return values. It covers purpose, ordering, pagination, and a key limitation (no page bodies), making it 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 has no descriptions for limit/offset (0% coverage). 'Paginated' hints at their purpose but doesn't explicitly explain each parameter or how they interact. However, for a simple list tool with standard pagination semantics, this is adequate baseline.

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

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

The description uses a specific verb ('List') and resource ('pages you have published to dochost'), with additional detail on ordering ('newest first'). This clearly distinguishes it from siblings like get_page (single page) and publish/update/delete (mutations).

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 appropriate usage: it lists the user's own published pages, is paginated, and returns compact records without page bodies, hinting that get_page should be used when full content is needed. While no explicit alternatives are named, 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?

The annotations provide readOnlyHint false, openWorldHint true, and destructiveHint false. The description adds meaningful behavioral details: plan-dependent link lifetime, password protection, slug, and branding, plus the default branding behavior for paid plans (no branding unless noBranding:false). These go beyond the structured metadata and help the agent anticipate outcome variations.

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-loaded with the core action and output. Each sentence adds useful information (format support, plan constraints, branding behavior) without any redundant or excessive 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 description covers the tool's primary purpose, the return value (shareable URL), and plan-dependent behavior. An output schema exists to define return structure, so that is not required here. It does not discuss error cases or authentication prerequisites, but the sibling get_account implies an account context, making this acceptable.

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 0%, so the description carries the burden of explaining parameters. It gives semantics for format, password, customSlug, and noBranding (e.g., 'pass noBranding: false to keep the mark'), but it does not explain public or body. Given the required body is obvious, but public's meaning is left unspecified, this is only partially compensative.

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 tool's function with a specific verb+resource: 'Publish Markdown or HTML as a hosted dochost page and get a shareable URL.' This distinguishes it from sibling tools like update_page, get_page, and delete_page, which handle reading, updating, or deleting existing pages.

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 the tool is for creating new hosted pages, but it does not explicitly state when to use it over update_page or list_my_pages. It gives context about plan entitlements, which helps set expectations, but lacks explicit alternatives or 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?

The description adds several behavioral traits beyond the annotations: 'The URL, view/like counts, and expiry stay the same; only the body, format, and title change,' and 'Resending identical content is a no-op.' This gives the agent context about state preservation and idempotency, complementing the destructiveHint and openWorldHint annotations without contradicting them.

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 sentences long, front-loads the core action, and every clause adds value. The second sentence provides a clear usage heuristic and a rationale, with no redundancy or 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?

The description is complete for a mutating operation: it states what is changed, what is preserved, idempotency behavior, and when to prefer it over the sibling publish tool. Since an output schema exists, not explaining return values is appropriate. It covers all necessary operational context despite the absence of parameter schema descriptions.

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?

With 0% schema description coverage, the description compensates by explaining the effect of three parameters (body, format, title) via 'only the body, format, and title change.' It does not explicitly describe the 'slug' parameter, but it is implied as the page identifier ('one of your pages') and needed for 'in place' replacement. The enum for format is not elaborated, but schema provides that.

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 'Replace the content of one of your pages in place,' which is a specific verb-resource pairing that clearly states the action. It distinguishes itself from siblings by contrasting with publishing again, naming the exact fields that change (body, format, title) and what stays the same (URL, counts, expiry).

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 explicit when-to-use guidance: 'Prefer this over publishing again whenever the user is revising something you already published for them,' and explains why over publishing is harmful ('a second publish creates a second link and strands the one they already shared'). This clearly differentiates from the sibling publish tool.

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