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 this as a read-only, non-destructive, closed-world operation, so the bar is lower. The description still adds real value by disclosing the returned entitlement categories and the important constraint that the primary host is configured in the dashboard, not through this API.

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, front-loaded with the return contents and followed by usage guidance and one caveat. The entitlement list is long but each item is informative, 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?

Although an output schema exists and the description need not explain return values, it covers purpose, when/when-not to call, and a behavioral constraint. Nothing an agent needs in order to decide whether to invoke this parameterless read 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 tool takes zero parameters, so the schema-based baseline of 4 applies. The description correctly implies no input is needed, describing only the information returned rather than any arguments.

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 verb and resource and then enumerates exactly what is retrieved: plan, page-quota usage, entitlement flags, and the primary publish host. That level of detail clearly separates it from siblings like get_page, get_page_content, and publish.

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 both when to call (need plan limits, domain details, paid-option availability) and when not to (a basic publish can use defaults without this extra call). It also flags that the primary host is set in the dashboard rather than via the API, removing a likely mis-invocation path.

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?

Annotations only declare a non-read-only, open-world, non-destructive operation; the description adds substantial context beyond that: HTML JavaScript runs in a sandbox, free links expire after seven days, paid lifetime follows entitlements, results report expiry and ignored options, and the agent must relay ignoredOptions/ignoredNote rather than overclaim. It also pins the host source (account primary host, visible via get_account).

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?

Front-loaded with purpose and activation condition, then capability/limitation detail; sentences are dense and mostly earn their place. Slightly long for a 6-param tool, and the trailing get_account sentence is marginally tangential, keeping it below a 5.

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 annotations covering safety and an output schema covering return shape, the description still supplies the operational caveats an agent needs: sandbox execution, expiry model, entitlement-gated options, and the ignoredOptions relay obligation. Nothing essential for a correct call 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%, so the baseline is 3, but the description adds cross-parameter semantics the schema only implies: password/customSlug are 'subject to plan entitlement', free vs. paid expiry behavior, and the instruction to check ignoredOptions before claiming settings were applied. That meaningfully improves how an agent sets and trusts these fields.

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 HTML or Markdown as a hosted web page') plus the concrete artifact (shareable URL), and explicitly distinguishes itself from update_page for revisions. An agent can route publish vs. update_page without opening either 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 an explicit activation condition ('Use when the user asks to share an HTML quiz, calculator, report or Markdown document as a link') and names the alternative tool with the condition that selects it ('For revisions of an existing page, use update_page to keep the same link'). No exclusions 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.

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.