ship.page

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the bar is lower. The description adds value by specifying permanence ('cannot be recovered'), immediate effect ('stops serving immediately'), and auth requirement ('sp_ API key'), which are beyond annotation scope. 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 two sentences, front-loading the purpose and then providing essential behavioral and auth context. Every part adds value with no 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 low complexity (one param, no enums, no nested objects), and that annotations and schema cover destructive nature and param details, the description is complete enough. It could add what the output looks like (though output schema exists), but it still feels sufficient.

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 baseline is 3. The description adds no parameter-specific details beyond the schema, but the schema itself clearly documents slug as the subdomain part of the URL. The tool has only one simple parameter, so the description's lack of extra parameter context is acceptable.

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's action ('Permanently delete a drop'), specifies the resource ('a drop owned by the authenticated account'), and differentiates it from siblings like deploy_files or list_drops by emphasizing destruction.

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 states the requirement for an 'sp_ API key' and provides consequences of use ('URL stops serving immediately and cannot be recovered'). It implies when to use (when permanent deletion is needed) but lacks explicit alternatives or 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 indicate it is not read-only, idempotent, or destructive. The description adds behavioral context about file limits (100 free, 900 pro), a 7-day expiry for free, and named drops for paid users. This goes beyond the annotations by explaining practical usage limits and restrictions.

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 very concise, front-loading the core function in the first sentence, then clearly listing constraints in a bullet-like style. Every sentence 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?

Given the complexity of the tool (3 params, nested files object, output schema present), the description is complete. It covers the core action, file limits, TTL behavior, and naming details. The output schema exists, so explaining return values is not needed.

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 parameters are well-documented in the schema. The description adds value by explaining the free vs pro implications for ttl and name, such as 'Free: max 604800' and 'Paid: any value'. It also clarifies the required presence of index.html, which is not in 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 uses a specific verb 'Deploy' and clearly identifies the resource as a 'map of path -> content as a multi-file site'. It distinguishes this tool from siblings like 'deploy_html' (which likely handles a single HTML file) and 'list_drops' or 'delete_drop' by focusing on the multi-file deployment action.

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 clear context on when to use this tool (to deploy multiple files as a site) and includes important constraints like requiring index.html and limits based on subscription (free vs pro). However, it does not explicitly state when not to use it or how it compares to alternatives like deploy_html for single-file cases.

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 not read-only, not idempotent, not destructive. Description adds critical behavioral context beyond annotations: rate limits (10 deploys/min per IP), size limits (10MB), and 7-day expiry for free tier. No contradictions 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?

Two sentences, front-loaded with the primary outcome (returns live URL), then compactly covers rate limits, size cap, expiry, and paid features. Every sentence adds distinct value with no 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?

With output schema present, return values are handled externally. Description fully covers the tool's purpose, constraints (rate, size, expiry), tier differentiation, and naming behavior. No gaps given the tool's complexity and supporting structures.

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 each parameter is described in the schema itself. Description adds no new parameter details beyond what the schema provides. Baseline 3 is appropriate since schema fully documents parameters.

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 tool deploys an HTML document and returns a live URL with specific format. It distinguishes from sibling tools like deploy_files (multiple files) and delete_drop (deletion). The verb 'deploy' and resource 'HTML document' are specific.

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 details usage context: anonymous vs. paid tier restrictions (rate limit, size cap, expiry), plus naming for paid users with vanity subdomain. This helps the agent choose between anonymous deployment (using defaults) or paid features, and distinguishes from deploy_files.

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, idempotentHint, and destructiveHint, covering the safety profile. The description adds the important behavioral trait that an sp_ API key is required, which is extra context beyond the annotations. 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 sentences, each earning its place. The first covers purpose and authentication requirement; the second provides an alternative for anonymous users. Front-loaded and concise with 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 output schema exists, the description is complete for a zero-parameter tool. It addresses the key scenario (authenticated vs anonymous) and specifies the returned data fields.

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 description has no burden to explain parameters. It adds meaning by specifying what the tool returns (plan, subscription status, usage), which is useful 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 tool shows the authenticated account's plan, subscription status, and usage. It distinguishes itself from the sibling get_limits by specifying that anonymous callers should use that tool instead, providing a clear differentiation.

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 states when to use the tool (authenticated users with an sp_ API key) and when not to (anonymous callers should use get_limits). This provides clear guidance on alternatives and context.

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, idempotentHint=true, and destructiveHint=false, so the description's main behavioral addition is the conditional API key requirement and the fact that it returns the plan matrix regardless. This adds useful but limited context beyond what annotations provide.

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 well-crafted sentence front-loads the plan matrix details and adds the important conditional logic about API keys. Every part is essential and there is no wasted text.

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 existence of an output schema and the tool's simple nature (0 params, clear conditional behavior), the description is nearly complete. It could be slightly improved by hinting at what the output structure covers, but the output schema fills that 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 description coverage is 100% and there are 0 parameters, so no parameter documentation is needed. Baseline of 3 is appropriate—the description adds no parameter information but nothing is missing either.

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 shows the ship.page plan matrix and, conditionally, the caller's account/plan status. The verb 'show' and specific resources (plan matrix, account status) are precise, and the tool is easily distinguishable from sibling tools like get_account.

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 clarifies that account/plan status is only shown 'when an sp_ API key is present', providing clear context for when the tool provides full vs. partial output. However, it does not explicitly state when to use this tool versus siblings like get_account, which might also reveal plan info.

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, idempotentHint, destructiveHint), the description adds meaningful behavioral context: authentication requirements, what fields are returned (slug, url, name, file counts, expiry), and the ordering (newest first). This helps the agent understand the tool's behavior without relying solely on the schema or 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 a single, well-structured sentence that front-loads the purpose, then adds constraints and return details. Every element earns its place with no redundancy or 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?

For a read-only list tool with an output schema and well-documented parameters, the description covers authentication, returned fields, and sorting order. It lacks mention of error conditions (e.g., invalid API key) or rate limits, but these are secondary for a simple listing 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 100% with detailed descriptions for both limit and offset. The description does not provide additional parameter-level information beyond what the schema already offers. Baseline 3 is appropriate as the schema itself is sufficient.

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 'List' and the resource 'drops owned by the authenticated account,' which distinguishes it from siblings like delete_drop and deploy_files. It also specifies the required API key and what fields are returned, making the tool's purpose unambiguous.

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 requires an sp_ API key and notes that anonymous drops are not listable, providing clear context for when this tool can be used. No explicit comparison with other tools is needed since list_drops is the only listing tool among the siblings.

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