dochost-mcp

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

Beyond the destructiveHint annotation, the description adds details: the deletion is permanent, the link stops working immediately, the slug is freed, and deleting an already-deleted page is a safe no-op. This fully discloses the 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 three concise sentences with no redundant words. It is well-structured and front-loads the primary action, then explains consequences and edge-case behavior.

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 delete operation with one parameter and an output schema, the description covers the effect, the idempotency, and the side effect on the slug. No additional information is needed for correct invocation.

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

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

Schema coverage is 0% for the slug parameter. The description says 'by slug' which conveys it is the page identifier, but offers no explanation of format, length constraints, or how to obtain the slug. Minimal compensation for the lack of schema description.

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 (page), and the identifier (slug). It is distinct from sibling tools such as update_page, publish, and 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?

The context is clear: use this tool to permanently delete a page. It does not explicitly exclude other tools, but the deletion intent is unambiguous and no competing tool serves the same purpose.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by revealing behavioral details beyond the annotations: the call should happen before publishing, and the primary host is set in the dashboard (manageDomainsUrl) rather than through this API. This helps an agent understand the tool's role and limitations.

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 tightly written sentences. The first sentence front-loads the returned data, and the second provides use-case timing and a key limitation. No filler or redundant phrasing—every clause adds practical guidance.

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, the readOnly annotation, and an existing output schema, the description covers what an agent needs to know: what data is returned, when to call it, and one important caveat (host maintenance is in dashboard). There are no gaps in call prerequisites or expected 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?

With zero parameters and 100% schema coverage, the schema fully describes the empty input. Baseline for 0 params is 4, and the description appropriately focuses on what the returned data represents (plan, quotas, flags, host) rather than inventing parameter semantics. It adds no parameter detail, but none is needed.

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 clearly enumerates the exact resources returned: plan, page-quota usage, entitlement flags, and primary host. This differentiates it from page-level siblings like get_page and list_my_pages by focusing on account-level data rather than individual 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?

It gives explicit timing guidance: 'Call before publishing so you know your limits up front.' It also clarifies that the primary host is chosen in the dashboard and not through this API, setting a boundary on what the tool cannot do. However, it doesn't explicitly contrast with sibling alternatives like list_my_pages or get_page, which would make the guidance stronger.

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 safety profile is covered. The description adds that it never returns the page body or password, which is useful. However, it doesn't mention potential errors (e.g., slug not found, permission issues) or pagination (not relevant here). 3 is appropriate given annotations already cover the read-only 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 concise and well-structured. It front-loads the purpose and the key information (what fields are returned), then adds the important exclusions and alternatives. Every sentence contributes to the agent's decision-making. No fluff.

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 is simple (1 param), has an output schema (which presumably explains return structure), and annotations cover safety, the description is quite complete. It lists the returned fields and clarifies it does not return the body or password. Slight gap: it doesn't mention the output schema's content or possible error behavior, but the output schema likely covers that. Overall, a very effective description for its 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 coverage is 0%, so the description must compensate. The description explains that the single parameter 'slug' is used to identify the page, and it implies the format and constraints (max length 64, min length 1) from the schema. The description adds the meaning of the parameter (page identifier) and its role in retrieving the specific page.

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 a page by slug and enumerates the specific fields it returns (title, format, status, counts, expiry, password-protection, visibility/indexing/branding). It explicitly distinguishes from siblings by mentioning get_page_content and set_page_options.

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 strong usage guidance: it tells the agent when to use this tool (to get page metadata/state) and when to use alternatives (get_page_content for the body, set_page_options to change settings). This explicit routing is exemplary.

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 readOnlyHint true and destructiveHint false, and the description adds meaningful behavioral context: update_page replaces content wholesale, version/sha can be passed as ifVersion/ifSha to avoid overwriting unseen changes, and expired pages remain readable and republish on the same URL. This goes well beyond the annotations.

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

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

Three sentences with no filler: the primary read action comes first, the critical update_page caveat follows, and the expired-page note finishes. Every sentence earns its place and the structure is skimmable.

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 with one required slug parameter, has an output schema, and carries read-only annotations, so the description only needed to add write-safety and concurrency behavior, which it does thoroughly. Nothing an agent needs to call it correctly 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 0% and the description never mentions slug, its format, or how it identifies the page. The tool name and schema imply slug is a page identifier, but the description does not add meaning beyond the schema to compensate for the low 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?

Description opens with the exact action and resource: 'Read back the CURRENT Markdown or HTML of one of your pages.' It also frames itself against update_page and clarifies it returns content plus version/sha, distinguishing it from siblings 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?

It explicitly states when to use: 'Call this before update_page whenever you did not write the live content yourself in this same conversation.' It also explains why, and notes expired pages are readable and can be republished, giving clear context for when this read tool is appropriate.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description adds genuinely useful behavioral traits: ordering ('newest first'), pagination behavior ('Paginated'), and output shape ('compact records, no page bodies'). This tells the agent what it will and won't get back without contradicting any 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 short sentences totaling about 18 words, with zero filler. The verb and resource are front-loaded, and every clause earns its place: scope, ordering, pagination, and output-shape caveat.

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 listing tool, this is nearly complete: scope, order, pagination, and record content are all disclosed, and the annotations plus existing output schema cover safety and return structure. The only gap is not explicitly routing the agent to get_page when a page body is needed, which is a minor omission given the sibling list is visible.

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 adds the concept of pagination, which gives semantic context for limit/offset, but it does not explicitly say limit controls page size and offset controls the starting position. The compensation is partial, so a middle score 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 states a specific verb ('List'), a resource ('the pages you have published to dochost'), and an ordering guarantee ('newest first'). It naturally distinguishes from siblings: it is a list/scoping operation, whereas get_page presumably fetches a single page, and publish/update/delete_page are 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 gives clear context: it is scoped to the caller's own published pages and is suitable for browsing/list operations. The 'no page bodies' note implies that content retrieval belongs elsewhere, but it never explicitly names get_page as the alternative for full bodies, 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?

Beyond annotations, the description discloses plan-sensitive behavior, branding defaults, partial success with ignoredOptions + ignoredNote, and host selection based on account settings. It also points to get_account for host confirmation. This is rich behavioral context and aligns with openWorldHint=true.

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 dense sentences, each earning its place: core purpose, plan entitlements, branding caveat, partial-success behavior, and host resolution. Information is front-loaded 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?

The description covers the essential operational context: what content is accepted, how entitlements affect options, what happens when options are ignored, and where the link is hosted. An output schema exists, so return-value details do not need to be repeated. For a 6-parameter publish tool, this is 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?

Schema description coverage is 0%, so the description must compensate. It explains format via 'Markdown or HTML', customSlug via 'custom slug', password via 'password protection', and noBranding explicitly with default behavior. The public parameter is not explained, and body is only implied as the content being published, leaving a small 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?

Description opens with a specific verb and resource: 'Publish Markdown or HTML as a hosted dochost page and get a shareable URL.' This clearly differentiates publish from siblings like update_page, delete_page, and get_page by focusing on creation of a new hosted page with a shareable link.

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 conveys the main use case: creating a new hosted page from Markdown or HTML. It also explains when plan limitations matter and tells the agent to relay ignoredOptions/ignoredNote instead of plain success, which is actionable usage guidance. It does not explicitly name alternative tools, but the creation-focused language makes the use case unambiguous.

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 mutating (readOnlyHint=false) and non-destructive, but the description adds plan-check semantics for paid capabilities, the forced-private behavior of passwords, the refusal of public+password rather than silent resolution, and the invariance of URL/view count/content. This is rich behavior context that aligns with openWorldHint.

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?

Five sentences, each adding a distinct, necessary piece of information: core behavior, alternative, partial-update semantics, entitlement rule, conflict rule, and an exclusion with a pointer to the alternative. No fluff 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 mutation tool with plan-dependent behavior, the description covers purpose, alternatives, edge cases, exclusions, and partial updates. The presence of an output schema means return-value description is unnecessary, and the only minor gap (permissions) is not critical given sibling 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?

Schema descriptions cover 80% of parameters, including rules for public, searchable, and removePassword. The description adds cross-parameter semantics: password forces private, public+password is refused, turning a paid capability off never requires entitlement, and only changed fields should be sent. This goes beyond the schema's per-property notes.

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 ('Change'), resource ('published page's settings'), and scope ('visibility, search-engine indexing or password'), and explicitly contrasts with deleting/republishing, which differentiates it from siblings like delete_page and publish. The title is equally clear.

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 instructs to use this instead of deleting and publishing again to preserve the shared link, and tells agents to send only changed fields. It also gives a when-not-to-use by declaring branding is not settable and points to get_page for brandingHidden.

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

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

The annotations already mark this as destructive and read-write, and the description builds on that by stating exactly what changes (body, format, title) and what stays the same (URL, counts, expiry). It also discloses the no-op behavior and the overwrite-protection semantics of ifVersion/ifSha, which goes well beyond the structured fields.

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 longer than average but every sentence earns its place: it front-loads the core action, then covers side-effect preservation, no-op behavior, selection over publish, and the overwrite warning. There is no filler or repetition of schema fields.

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

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

For a destructive write operation with six parameters and no reference documentation, this description provides all necessary context: when to use it, what it changes, what it preserves, and how to avoid clobbering unseen edits. The presence of an output schema means return-value details do not need to be repeated.

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 does for the riskiest parameters by explaining ifVersion/ifSha as conditional overwrite guards and warning that body replacement is whole-page. It adds less detail for slug, title, and format, though those are largely inferable from the schema and the tool's purpose.

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 precise verb and resource: 'Replace the content of one of your pages in place.' It clearly distinguishes this tool from the sibling 'publish' by explaining that this edits an existing page rather than creating a second link, so an agent can instantly tell them 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?

The description explicitly says to prefer this over publishing when revising already-published content, and explains why publishing again is worse. It also gives a concrete precondition: call get_page_content first and pass back the version/sha256 unless the agent wrote the live content itself.

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