dochost-mcp

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

Annotations already mark the tool as destructive (destructiveHint: true). The description adds that deletion is permanent, immediate (link stops working), and idempotent (no-op if already deleted). It also specifies that the slug is freed. 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 three sentences long, each providing essential information: the action, effects, and idempotency. It is front-loaded with the main purpose and avoids unnecessary 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?

For a simple destructive tool with one parameter and an output schema (not shown but present), the description covers the purpose, input, effects, and idempotency. It does not mention the return value, but that is likely covered by the output schema. It is adequate for the 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?

The input schema has 0% description coverage for the 'slug' parameter. The description only mentions 'by slug' but does not explain what a slug is, its format, or how to find it. While the parameter name is self-explanatory in context, the description adds minimal value 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 description clearly states the action ('Permanently delete') and the resource ('one of your pages'), and specifies the identifier ('by slug'). It distinguishes from sibling tools like get_page, update_page, and list_my_pages by indicating this is the deletion tool.

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 explains when to use the tool (to permanently delete a page), how to specify the page (by slug), and notes that deleting an already-deleted page is safe. It does not explicitly state when not to use it or list alternatives, but the context from sibling names makes the 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 declare readOnlyHint=true and destructiveHint=false, confirming safety; description adds what specific data is returned and a practical usage hint, exceeding minimal 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?

Two concise, front-loaded sentences: first states what is returned, second provides actionable guidance. 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?

Given zero parameters, rich annotations, and an output schema, the description fully covers what the tool does and when to use it.

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?

No parameters exist (schema coverage 100%), so description need not elaborate; baseline of 4 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 clearly states the tool retrieves account details (plan, quota, flags) from 'dochost account', distinguishing it from sibling tools like get_page or list_my_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?

Explicitly advises calling before publishing to know limits, providing clear context for when to use this tool effectively.

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 destructiveHint=false. The description adds value by specifying what is returned (metadata fields) and what is explicitly excluded (page body, password), which is beyond the annotations. It could have mentioned response structure, but that is covered by the output schema.

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

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

The description is two sentences long: the first sentence states the function and lists returned fields, the second clarifies what is never returned. It is front-loaded, concise, and every sentence adds value without redundancy.

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

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

Given the tool's simplicity (1 parameter, read-only, with output schema and annotations), the description provides all necessary context: what it does, what it returns, what it doesn't, and how to specify the page. No gaps are apparent.

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

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

The schema has one required parameter 'slug' with basic constraints (string, 1-64 chars). The description references 'by slug' but adds no additional meaning such as format, examples, or behavior beyond what the schema provides. Schema description coverage is 0%, but the parameter is simple.

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 'page by slug', lists exactly which metadata fields are returned (title, format, status, view/like counts, expiry, password-protected), and explicitly states what is never returned (page body, password). This clearly distinguishes it from siblings like delete_page, publish, and update_page.

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 indicates when to use the tool: to retrieve page metadata by slug. It implicitly advises against using it to get the page body or password, as those are not returned. However, it does not explicitly state when not to use it or mention alternatives like list_my_pages to find slugs first.

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, destructiveHint=false. Description adds beyond annotations: 'newest first', 'paginated', 'returns compact records (no page bodies)'. No contradictions.

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 clear sentences, front-loaded purpose, 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 list tool with output schema, description covers purpose, ordering, pagination, and return format. Siblings cover other actions.

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 limit and offset with min/max. Description mentions 'paginated' hinting at parameters. While schema coverage is 0%, parameter names are self-explanatory and description adds context about ordering and compact records.

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?

Description clearly states 'List the pages you have published to dochost, newest first.' Specific verb+resource+scope distinguishes from siblings like delete_page, get_page, publish, update_page.

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?

Implies when to use (listing own pages), but lacks explicit 'when not to use' or alternatives. However, given sibling tools, usage is clear.

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

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

Annotations indicate mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds value by noting the resulting shareable URL and plan-respecting behavior, but does not detail error handling or rate limits.

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 with no wasted words. The first sentence states core action, the second adds valuable context about plan entitlements. Front-loaded and efficient.

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 an output schema exists (not shown), the description's mention of a shareable URL suffices. It covers key features (password, slug, branding) but omits handling of invalid body or plan enforcement errors. Adequate for a typical publish tool but not exhaustive.

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%, requiring the description to compensate. It mentions password, slug, and branding but does not explain key parameters like 'format' (enum markdown/html) or 'public' boolean. The mapping between description claims and actual parameters is incomplete.

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

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

The description clearly states the verb (publish), resource (dochost page), and output (shareable URL). It distinguishes from sibling tools like delete_page, update_page, and list_my_pages by specifying creation of a new hosted page.

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 explains that behavior depends on the user's plan (link lifetime, password, slug, branding), which guides usage expectations. However, it does not explicitly state when to avoid this tool or mention alternatives for modifying existing pages.

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 signal destructiveness (destructiveHint=true). The description adds value by clarifying that URL, counts, and expiry persist, and that identical content is a no-op – details not evident from annotations.

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

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

Three sentences, each purposeful. Front-loaded purpose, followed by preserved attributes, then no-op behavior. Zero unnecessary 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?

Despite having an output schema and good annotations, the description omits explanation of the slug parameter and any prerequisites. However, the tool is simple and the core behavior is adequately covered for an update operation.

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

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

Schema coverage is 0%. Description mentions only body, format, and title change, but fails to explain the required slug parameter or add meaning to format's enum choices. Parameter semantics rely almost entirely on 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?

Description states 'Replace the content of one of your pages in place' – a specific verb and resource. It clearly distinguishes from siblings like delete_page (destruction) and get_page (reading) by emphasizing mutation while leaving other attributes unchanged.

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 updating page content but provides no explicit when-to-use guidance or comparison with alternatives like publish or delete_page. Sibling names are given but not leveraged in the text.

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