deed.page

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real behavioral value beyond that: the deletion is permanent and the slug becomes free for reuse, which matters for an agent deciding whether this is reversible.

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 tight sentences with no waste; the usage caveat and the destructive consequence are both front-loaded and easy to scan.

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 single-parameter delete with annotations carrying the safety hints and no output schema, the description covers everything needed to invoke it correctly. Only a note on any error/irreversibility behavior 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% and both parameters (slug, token) are already fully described in the schema, including the optional auth path. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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 (permanently removes) and resource (the slug you own), which cleanly separates it from update_site or publish_site. It does not explicitly name a sibling, but the destructive/permanent framing makes the operation unmistakable.

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 an explicit usage condition: 'Use this only when the user explicitly asks to take a site down.' This is a clear when-to-use gate that guards against accidental deletion, though it does not name alternative tools for other removal/recovery scenarios.

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 and openWorldHint, so safety is largely covered; the description still adds that the operation is public with no token required, an auth fact the annotations don't capture. It also previews return fields, useful given there is no 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?

Two short sentences, front-loaded with the primary purpose and ending with the auth caveat. 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?

For a one-param read with no output schema, the description compensates by listing the returned fields and the public/no-token access model. It doesn't say what happens on a missing or invalid slug, a minor gap.

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% and there is a single 'slug' parameter already documented in the schema, so the baseline is 3. The description adds no format, case, or resolution detail 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?

States a specific verb+resource (get site info) and enumerates the returned fields (URL, version, size, timestamps) plus a secondary check (is the slug live). This is clear, though it doesn't explicitly distinguish itself from siblings like list_sites or get_upgrade_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?

Gives a concrete use case — 'check whether a slug is live and read its URL, version, size, and timestamps' — which orients the agent on when to reach for it. No explicit when-not or named alternative, so short of the top band.

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 say readOnlyHint=true and openWorldHint=true; the description goes further by clarifying that nothing is charged, that a human must open the URL and complete payment, and that the link is tied to the caller's token. That resolves the real ambiguity behind 'read-only' for a payment-adjacent tool, though it omits link expiry or failure 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?

Three short sentences with zero padding, front-loading the usage restriction before the return value and the payment caveat. Every sentence carries distinct information.

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?

There is no output schema, so the description must characterize the return value — and it does, naming the Stripe Checkout URL and the billing consequence. For a two-parameter, single-purpose tool, an agent has everything needed to call 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?

Schema coverage is 100%, so the baseline is 3, but the description adds information the schema lacks: the concrete prices for each enum value ($3/mo Hobby, $15/mo Pro) and the token's origin (deed_tok_ from first publish). The token's optionality is covered by the schema rather than the 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?

States a specific verb+resource (returns a Stripe Checkout URL) and names both plan tiers with prices. Nothing about it overlaps with the site-management siblings, so an agent can immediately tell this is the monetization/upgrade 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?

Gives an explicit gating condition — 'Use this only when the user asks for higher limits' — which is a clear when-to-use with a restriction. It does not name an alternative path to upgrading, but no sibling tool offers one, so the gap is minor.

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 openWorldHint=false, so the safety profile is covered. The description usefully adds that results are limited to *live* sites and scoped to token ownership, but does not cover ordering, pagination, or empty-result 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?

A single front-loaded sentence with no filler; the action, scope, and returned fields are all in the first clause.

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 list tool with no output schema, the description compensates by naming the returned fields (URLs, versions) and the live-site filter. Adequate, though ordering and pagination remain unstated.

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 100% and the single token parameter is fully documented in the schema, so the baseline is 3. The description only echoes "your token" without adding format or fallback detail beyond what the schema already states.

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 (list) and resource (sites) plus the scope (every live site owned by your token) and the fields returned (URLs, versions). It is clearly distinguishable from get_site, though it never explicitly names the singular sibling as the alternative.

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?

"Use this to list every live site" implies the use case (enumerate all sites) but gives no when-not guidance or explicit routing versus get_site (single site) or whoami. Usage is inferable from the sibling set rather than stated.

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?

With readOnlyHint=false and openWorldHint=true already declared, the description still adds meaningful behavior: the URL is permanent, the return shape is {url, slug, version, token?}, and the token is issued only on the first anonymous publish and must be stored for later updates. That token lifecycle detail is real value beyond the annotations. It does not mention slug collision behavior or what happens to prior versions when publishing again.

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, each earning its place: trigger, action, and return contract. The stance call is front-loaded and nothing is padded.

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 6-param mutation tool with no output schema, the description compensates by spelling out the return object and the token lifecycle, and annotations cover the safety/open-world profile. Remaining gaps (merge vs. replace semantics, ttl interaction) are documented in the schema, so this is nearly 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 100%, so every parameter (spa, slug, files, merge, token, ttl_seconds) is already documented in the schema, and the description adds no parameter-level detail. Baseline 3 is correct when the schema does the heavy lifting.

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+resource ('Publishes files to a live permanent URL at the chosen slug') and frames the user intent ('wants something put online, shared as a link, or hosted'). Clearly distinguishable from delete_site, get_site, list_sites, and update_site.

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 trigger condition tied to user intent, which is strong usage guidance. It does not, however, name the sibling update_site/delete_site as alternatives for editing or removing an already-published site, so routing between publish and update is 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 declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is partly covered. The description still adds real value beyond them: the auth requirement (token from first publish, or Authorization: Bearer), the merge/replace distinction, and the return shape with a bumped version. It doesn't say whether omitted files are deleted in non-merge mode, which is precisely the destructive question the annotation raises.

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 tight sentences with zero filler; the core replace-vs-merge semantics and the prerequisite token lead, and the return behavior trails. Every clause carries information an agent needs.

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?

A destructive 5-parameter mutation with no output schema and nested file objects; the description covers the precondition, the destructive/replaceive nature, and points to publish_site's shape for the return. It is nearly complete, though the exact fate of files not included under a non-merge update remains unstated.

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 100%, so the schema already documents slug, files, merge, token and spa. The description restates the merge semantics already present in the schema's own description ('Keep existing files and add/overwrite only these paths') without adding format or syntax detail beyond it. Baseline 3 is correct when the schema does the heavy lifting.

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 (replace/add) and resource (the files of a slug you already own), and the merge=true qualifier immediately distinguishes the additive case from the replacement case. An agent can tell this apart from publish_site (which creates a new slug) 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?

The phrase 'a slug you already own' plus 'Requires the token from the first publish' establishes the precondition for using this tool versus publish_site, which is clear context. It stops short of naming publish_site as the alternative for new slugs or stating when-not to use it, so it earns a 4 rather than 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 openWorldHint=false, so the safe-read profile is covered. The description adds what is returned (plan, limits, owned-site count), but says nothing about auth requirements, quota semantics, or the token's optionality beyond what the schema already states.

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?

One efficient sentence with the payload front-loaded and no filler. Slight redundancy between 'limits' and 'how many sites your token owns', but overall tight.

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 zero-required-param read-only tool with annotations covering safety and no output schema, the description states what the caller gets back. It is essentially complete; only auth/quota nuance is left implicit.

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 100% for the single optional 'token' parameter, so the schema fully documents it (format, optionality, Authorization fallback). The description adds no parameter-level detail, which is the correct baseline when the schema does the heavy lifting.

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 ('read') and resource ('your plan, limits, and how many sites your token owns'), which is an account/identity read clearly distinct from the site-scoped siblings (get_site, list_sites, publish_site). It doesn't explicitly name a sibling to route away from, but the resource itself separates it from all six.

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?

'Use this to read...' implies intent but gives no when-not guidance or alternatives (e.g., the difference from list_sites when checking site ownership). Usage is inferable from the resource, not spelled out.

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