dochost

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

The description adds significant behavioral details beyond the annotations: 'permanently delete', 'link stops working immediately', 'slug is freed', and 'safe no-op' for already-deleted pages. Annotations already indicate destructiveHint=true and readOnlyHint=false, and the description reinforces and expands on these.

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 with no wasted words. It is front-loaded with the primary action and includes all necessary details in a compact form.

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 low-complexity tool with one parameter, annotations, and an output schema, the description is complete. It covers the deletion action, immediate effects, and idempotency, providing all information needed for an agent to use 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?

The only parameter, slug, is described in the schema with min/max length. The description mentions 'by slug' but does not add further semantic meaning or formatting guidance. With schema coverage at 0%, the description should compensate, but it only minimally connects the slug to the 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 verb (delete), resource (page), and the identifier (slug). It distinguishes from sibling tools like get_page, update_page, etc., by specifying that the action is permanent 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 provides context on when to use the tool (to delete a page by slug) and explains the effects: link stops working, slug is freed, and idempotency. However, it does not explicitly mention when not to use it or suggest alternatives, so it's slightly lacking in exclusionary 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, so the description adds value by specifying the exact data returned (plan, quota, flags). It does not mention any edge cases but covers core 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?

Two sentences, no fluff. Front-loaded with what the tool returns, immediately followed by a practical usage tip.

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 explains the return content and a primary use case. With an output schema present (though not shown), it does not need to detail return format. Sufficient for a simple read-only tool.

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, so baseline is 4. Description does not need to add parameter info, and it correctly omits any.

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 specific account info: plan, page-quota usage, and entitlement flags. It distinguishes itself from sibling tools that deal with pages, not account data.

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 advises using the tool before publishing to know limits, providing clear context. However, it does not explicitly mention when not to use it or alternatives, though none are needed given sibling scope.

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, aligning with the read-only nature. The description adds valuable behavioral context: it explicitly states that the page body and password are never returned, which is crucial for an AI agent to understand the tool's 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 sentences: the first efficiently conveys the action and return fields, the second states a key exclusion. There is no fluff, and the most important information is 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?

Given the presence of an output schema (per context signals) and the simple nature of the tool, the description covers all necessary aspects: what it does, what it returns, and what it explicitly does not return. No gaps.

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. It mentions 'by slug' but does not elaborate on the slug's format or where to obtain it. The parameter is simple, so the added value is minimal, but it is sufficient for a single required parameter.

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 single page by slug, listing specific metadata fields returned. It distinguishes itself from sibling tools like list_my_pages (which lists all pages) and delete_page or update_page (which modify).

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 use when you need a specific page's metadata by slug, but does not explicitly contrast with alternatives or mention prerequisites. It is clear enough but lacks exclusions or explicit 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 indicate read-only and non-destructive behavior. The description adds valuable details: sorting by newest first, pagination, and that records are compact (no bodies). No contradiction.

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 wasted words. Information is presented efficiently and in a logical order.

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, it covers the key aspects: ownership, sorting, pagination, and record format. Output schema exists but is not shown; however, description compensates with mention of compact records. Minor gap: no mention of maximum result set or whether offset counts from start.

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 describes limit and offset with constraints, but description only says 'paginated' without explaining parameters. With 0% schema description coverage, the description should compensate but does not provide sufficient semantic detail.

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 lists pages published by the user, sorted newest first. The verb 'List' and resource 'pages' are specific, and the title aligns. This differentiates it from siblings like delete_page or get_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?

No guidance on when to use this tool versus alternatives such as search or get_page. The description does not mention exclusions or context for selection.

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 a non-destructive write operation. The description adds plan-dependent behavior, branding options, and the ability to keep Dochost branding (noBranding parameter). It explains that link lifetime, password, custom slug, and branding follow account entitlements, which is useful contextual info.

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?

Description is two sentences. First sentence states the core purpose concisely. Second sentence adds important behavioral details. Every phrase earns its place 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?

For a tool with 6 parameters and an output schema, the description covers purpose, required input (body), format, and plan-specific behaviors. It mentions the output ('shareable URL') but does not detail the response structure; however, the presence of an output schema compensates. Minor gaps include no mention of the 'public' parameter, but overall it is quite 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 has 0% coverage, but description informally explains most parameters: format ('Markdown or HTML'), password protection (password), custom slug (customSlug), and branding (noBranding). It does not explicitly mention the 'public' parameter, but the context of password protection implies it. Overall, the description adds significant meaning beyond the raw 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 clearly states the verb 'Publish' and resource 'dochost page' and distinguishes from sibling tools which are CRUD and account management. It also specifies content types (Markdown or HTML).

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?

While not explicitly listing alternatives, the description makes it obvious that this tool is for creating new published pages, distinct from siblings like update_page or delete_page. The context is clear enough for an agent to decide when to use it.

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 show destructiveHint=true and readOnlyHint=false. Description adds context: URL, counts, expiry remain; resending identical content is a no-op. However, it doesn't detail any irreversible consequences or permission requirements beyond what annotations suggest.

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: first states core purpose, second adds behavioral details, third gives usage guidance. No unnecessary words; front-loaded with the primary action.

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?

Covers main effect and distinguishes from publish, but leaves gaps: no mention of error handling, slug validation, or required permissions. Output schema exists, so return values are not needed, but common edge cases are unaddressed.

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?

Input schema has 4 parameters with 0% description coverage. Description mentions 'body, format, and title change' but does not explain individual parameters like slug (likely the page identifier) or format enum values. Compensation for missing schema descriptions is insufficient.

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 'Replace the content of one of your pages in place' and specifies what changes vs stays same. Distinguishes from sibling 'publish' by noting that a second publish creates a new 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?

Explicitly instructs to prefer this over publish when revising, warning that a second publish strands the shared link. No guidance on when to use vs delete_page or get_page, but the main alternative is covered.

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