demo.st

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

With no annotations, the description carries the full burden of behavioral disclosure. The verb 'check' suggests a read-only operation, and the example clarifies the URL format. However, it does not disclose the return value format (e.g., boolean or other), nor does it mention any side effects, rate limits, or error behaviors. This is a moderate transparency gap.

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 sentence that front-loads the purpose and includes a useful example. Every element earns its place, with no unnecessary filler. It is well-structured for quick parsing.

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 parameter and no output schema, so the description should ideally explain what the tool returns. While the example clarifies the input/output domain, the absence of an explicit return type or behavior description leaves the agent uncertain about how to interpret the response. For a simple check tool, this is a notable 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?

The schema already fully describes the 'name' parameter with clear constraints. The description adds value by providing an example mapping ('my-site' → my-site.demo.st), which helps the agent understand how the input is used. This goes beyond the schema description, so a score above baseline is warranted.

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 purpose: to check if a subdomain is available on demo.st. The verb 'check' is specific, the resource is identified, and the example clarifies the output domain. It also distinguishes itself from sibling tools like reserve_subdomain and release_subdomain by focusing on availability.

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 usage contexts (e.g., before reserving a subdomain) but does not explicitly state when to use this tool versus alternatives. There is no mention of prerequisites or exclusions, so the guidance is implicit rather than explicit.

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 no annotations, the description must disclose behavior. It clearly states the action (removal) and the key consequence (subdomain remains reserved), which is helpful. However, it does not mention whether the action is reversible, requires permissions, or affects other resources, leaving some transparency gaps.

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 sentence that conveys both the primary action and an important distinction (subdomain reservation). Every word serves a purpose, and it is front-loaded with the 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?

For a zero-parameter tool with no output schema, the description covers the essential operation and the distinguishing detail. It could optionally mention prerequisites or idempotency, but for this simple operation, it is largely 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?

The tool accepts no parameters, so the input schema is empty. According to the rubric, 0 parameters gives a baseline of 4, and the description correctly does not attempt to describe nonexistent 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?

The description clearly states a specific action: removing deployed site content from a subdomain, and explicitly notes that the subdomain remains reserved, distinguishing it from sibling tools like release_subdomain and upload_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?

The description implies the tool is used when you want to clear content but keep the subdomain, and the 'Subdomain remains reserved' clause hints at a distinction from release_subdomain. However, it does not explicitly name alternatives or state conditions for use, so the guidance is implied rather than explicit.

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?

No annotations are provided, so the description carries the burden. It discloses naming rules and a site limit, which is useful, but it does not mention return values, failure behavior, or permissions. It adds some value but lacks full transparency.

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 that states the action and key constraints without any wasted words. Excellent structure.

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 one-parameter create tool with no output schema, the description covers the essential constraints (naming and limit). While it omits response details, the tool's simplicity makes this acceptable.

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 schema already describes the 'name' parameter at 100% coverage, but the description enriches it with format constraints (lowercase start, allowed characters, max length), adding meaning beyond the schema's simple example.

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 'Create a document collection' with a specific verb and resource, distinguishing it from sibling tools like delete_collection and list_collections. The naming constraints add precision.

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?

Usage is implied by the name and context (creating a new collection), but there is no explicit guidance on when to use this versus alternatives, nor any exclusions. The max-collections-per-site note provides some contextual 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?

With no annotations, the description carries the burden of disclosing behavior. It discloses the cascading deletion of all records, which is important, but it does not mention irreversibility, required permissions, or any side effects beyond the records themselves.

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 concise sentence that is front-loaded with the action and resource. Every word earns its place, with no filler 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?

The tool is simple with one parameter and no output schema. The description covers the target and the destructive scope, which is sufficient for basic invocation, though an explicit 'permanent' or 'irreversible' warning would make it more 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%, and the parameter description ('Collection name to delete') fully explains the name parameter. The tool description adds no extra semantic value beyond the schema, so the baseline of 3 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 clearly states the verb ('Delete'), the resource ('document collection'), and the scope ('all of its records'), which distinguishes it from siblings like delete_record. It is specific and 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?

No guidance is given on when to use this tool versus alternatives. It does not mention that delete_record should be used for individual records or indicate any preconditions or situations to avoid.

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 no annotations, the description must carry full behavioral disclosure. It only states the action without revealing permanence, required permissions, idempotency, error behavior, or side effects. It adds no context beyond the tool's name.

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, concise sentence that front-loads the verb and contains no redundant information. It is appropriately sized for the straightforward action being described.

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 operation with no output schema and no annotations, this description is too sparse. It omits expected return values, success/failure behavior, and situational context, leaving the agent without enough information to confidently invoke the 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?

The input schema already provides clear descriptions for both parameters ('Record id.' and 'Collection name.'), achieving 100% schema coverage. The description does not add further semantic meaning or usage details beyond those 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 clearly states the action ('Delete') and the target resource ('a record from a document collection'), which distinguishes it from siblings like delete_collection (deleting an entire collection). The verb+resource combination is specific and 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 offers no guidance on when to use this tool versus alternatives. It does not mention that delete_collection is for removing whole collections or that upsert_record handles creation/updates, nor any prerequisites or conditions.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the tool may create the key ('Get (or create)'), and that the tenant is scoped by the key, adding security context. It does not mention side effects like invalidation of previous keys, but for a simple tool, this is adequate.

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 only two sentences and is tightly packed with purpose, usage, and security warnings. 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?

For a tool with no parameters and no output schema, the description covers the essential aspects: what it does, how to use the result, and scoping. It implies the return value (the key) and mentions the prerequisite of a reserved subdomain, making it sufficiently complete for the tool's simplicity.

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 has zero parameters, so the input schema contributes nothing. The description compensates by explaining the key's purpose, the API endpoint, and authentication method. This exceeds the baseline of 4 for zero-parameter tools.

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 purpose with a specific verb and resource: 'Get (or create) the public site API key for your reserved subdomain.' This distinguishes it from sibling tools like rotate_site_api_key, and the context of 'public site API key' adds specificity.

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 provides direct usage guidance: 'Embed this key in your static site and call https://api.demo.st/v1 with Authorization: Bearer <key>.' It also warns about sharing keys, which helps the agent understand when to use this tool. It does not explicitly mention alternatives, but the context makes it clear this is for obtaining a key, not rotating one.

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?

No annotations are provided, so the description carries the burden of disclosing behavior. 'List' implies a read-only operation, and 'for your site' scopes the action, but the description does not mention return format, pagination, or any side effects. This is adequate for a simple list operation but lacks richness.

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 sentence that is immediately front-loaded with the action and resource. Every word serves a purpose, with no filler or 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 no parameters and a simple action, the description is nearly complete. It does not describe what is returned, but given the lack of output schema, 'List document collections' sufficiently implies a list of collections. The scope 'for your site' adds necessary 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?

The tool has zero parameters, and the schema is trivially covered at 100%. The description adds no parameter semantics because there are none to describe, which is consistent with the baseline of 4 for 0-parameter tools.

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 ('List') and a clear resource ('document collections for your site'), making the tool's function unambiguous. It naturally differentiates from sibling tools like create_collection and delete_collection, which perform operations on the same resource.

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 'for your site' clarifies that this lists collections within a particular site, but it does not explicitly exclude alternatives or mention when not to use it. However, the contrast with sibling tools (create, delete, upsert) makes the usage scenario clear enough for an AI agent.

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?

No annotations are provided, so the description carries the full burden. It states a 'List' operation, which implies read-only, but fails to disclose pagination behavior, error handling, or prerequisites like collection existence. Significant behavioral gaps remain.

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?

Single concise sentence, front-loaded with the primary action, and no unnecessary words. Highly efficient.

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?

Despite low schema complexity and no output schema, the description is minimal but adequate for a simple list operation. However, it does not mention pagination or response format, leaving moderate 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 description coverage is 100% with all parameters documented, so the baseline is 3. The description adds no parameter semantics beyond what the schema already provides.

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 'List records' with a specific resource (records) and context (document collection), making it distinct from sibling tools like list_collections and upsert_record.

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 verb 'List' implies it is for read-only inspection of records, but no explicit when-to-use guidance or alternatives are provided. The intended use is inferred 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 no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the tool deletes the reservation, deployed site, and all document DB data, which is critical destructive information. It does not mention irreversibility explicitly, but deletion implies it. Overall, it transparently discloses the major side effects.

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, efficient sentence that front-loads the primary action ('Release your reserved subdomain') and then enumerates the consequences. Every word earns its place; there is no redundancy or padding.

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 that there is no output schema and no parameters, the description covers the essential context: what is released and what is deleted. It does not describe return values or success indicators, but for a destructive operation, the key information is the scope of deletion, which is provided. Minor omission: it does not explicitly state that the action is irreversible, but that is implied by 'deletes.'

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 input schema has zero properties, so there are no parameter details to explain. The baseline for zero parameters is 4, and the description does not need to compensate for any missing parameter info. The description adds no parameter semantics because none exist.

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 ('Release') and clearly identifies the resource ('your reserved subdomain'). It goes beyond a simple definition by enumerating the specific effects: deleting the reservation, any deployed site, and all document DB data. This distinguishes it from sibling tools like reserve_subdomain and clear_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?

The description implies usage: release a subdomain you previously reserved. It lists the actions taken, helping infer the consequences. However, it does not explicitly state when to use this tool versus similar alternatives like clear_site, nor does it provide exclusions or prerequisites. Guidance is implicit rather than explicit.

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?

No annotations are provided, so the description carries full behavioral burden. It discloses that the reservation is for the logged-in account and that there is one subdomain per account, but it fails to mention what happens if the subdomain is unavailable, whether the operation is idempotent, if it can overwrite, or what the return value is. This is insufficient for a mutation tool with a uniqueness constraint.

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, front-loaded sentence that conveys purpose and a key constraint without any fluff. Every word earns its place.

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?

Despite being a simple tool, it has no output schema and minimal description. Missing information includes failure modes (e.g., if already reserved), behavior after reservation, and how it fits with release_subdomain. This is a notable gap for a tool with a uniqueness constraint.

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%, with the subdomain parameter clearly documented (letters, numbers, hyphens; 1-63 chars). The description adds no extra meaning 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?

The description uses the specific verb 'Reserve' with the resource 'subdomain' and the target 'logged-in account', clearly distinguishing it from sibling tools like check_subdomain_availability and release_subdomain. The constraint 'One subdomain per account' adds further specificity.

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 usage (to reserve a subdomain for the account) and notes a key constraint, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. Sibling tool names provide context but the description itself lacks explicit 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?

With no annotations, the description carries the full burden and does disclose the critical behavioral trait: the old key stops working immediately. This is a key side effect. However, it does not explicitly state that the new key is returned in the response, though it is implied by 'update your site with the new key.' Lacks mention of permissions or reversibility.

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 purpose, followed by the key consequence and required action. Every word earns its place; no fluff or 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 zero-parameter, security-sensitive action, the description covers purpose, immediate invalidation, and follow-up step. It could be more explicit about the response containing the new key, but the instruction to update the site with the new key implies it. No output schema exists, so the description partially compensates.

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 input schema is empty with 0 parameters, so the baseline is 4. The description adds no parameter-specific meaning but does not need to; the tool takes no 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?

The description clearly states the action ('Rotate the public site API key') with a specific verb and resource, and distinguishes it from siblings like get_site_api_key by focusing on rotation rather than retrieval. The sentence immediately clarifies what rotation entails.

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 when to use the tool by explaining the consequence ('The old key stops working immediately') and instructing to update the site with the new key. It indirectly warns against rotating unless ready to update, but does not explicitly name alternatives or exclusions.

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?

No annotations are provided, and the description does not disclose side effects, whether the upload overwrites existing content, authentication requirements, or any outcomes. It only states the action without behavioral context.

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 front-loaded, with the main purpose first, followed by clear parameter guidance in a structured list. Every sentence adds value.

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 a mutating upload with no output schema or annotations. The description omits critical context such as overwrite behavior, prerequisites like reserving a subdomain or API key, and what the response contains. This leaves the agent under-informed for successful 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?

The schema covers all parameters, but the description adds practical guidance: zip_base64 is highlighted as easiest for agents, and file_path is noted for local/stdio MCP. This enriches the parameter semantics 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 uploads a .zip as site content for a reserved subdomain, using a specific verb and resource. It distinguishes from sibling tools like clear_site and reserve_subdomain by focusing on uploading content.

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 usage for a reserved subdomain and provides guidance on choosing among parameters (zip_base64, file_url, file_path), but it does not explicitly state when to use this tool versus alternatives or when not 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?

No annotations are provided, so the description carries the burden. It discloses that the tool performs a write operation and explains the role of the optional id ('upsert a specific record'). However, it does not clarify whether updates are full replacements or partial merges (though the schema's id description says 'create or replace'), nor does it mention permissions, error handling, or return values. This is adequate but not rich.

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 filler. It leads with the primary purpose and immediately provides the key usage details. Every sentence earns its place.

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 mutation tool with no output schema or annotations, the description covers the basic operation and the id behavior. It does not explain return values, error cases, or whether the collection must exist, but it is minimally sufficient for the agent to understand core functionality. A more complete description would address these 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 description coverage is 100%, so the baseline is 3. The description adds minimal value: it repeats that data is an object and explains the id's purpose, but these are already in the schema. It does not introduce additional meaning for 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?

The description clearly states the action ('Create or update') and the resource ('a JSON record in a collection'). This distinguishes it from sibling tools that manage collections (create_collection, delete_collection) or delete records (delete_record). The verb is specific and the scope is well-defined.

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 for when to use the tool: when you need to create or update a JSON record. It does not explicitly exclude alternatives or name sibling tools, but the scenario is obvious. This aligns with 'clear context, no exclusions'.

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