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 transparently reveals idempotency behavior (existing email returns is_new_sign_up: false), return values (position, referral code, sign-up token), and cross-plan compatibility. However, it leaves ambiguity about whether subsequent calls with different data update existing subscriber fields, so it is not a perfect 5.

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 highly concise, consisting of two sentences that front-load the action, then return value, idempotency nuance, and compatibility statement. No words are wasted, and every sentence contributes meaningful context.

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 has a moderately complex schema (6 parameters, nested objects) and no output schema, but the description covers key return fields and edge-case behavior (idempotency, is_new_sign_up flag). It does not provide the exact response structure or error scenarios, but the level of detail is sufficient for an AI to select and invoke the tool 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 description coverage is 100%, so the baseline is 3. The description does not add extra parameter-level guidance beyond what the schema already provides; it only reinforces email-related behavior through the idempotency note. This is acceptable but does not elevate the score.

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 ('Add') with a resource ('subscriber') and context ('waitlist'), clearly distinguishing it from sibling tools like update_subscriber and delete_subscriber. It further clarifies the purpose by mentioning return values and idempotent behavior.

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 clearly states when to use the tool (adding a subscriber) and adds operational context (idempotent per email, works on every plan). It does not explicitly name alternatives or exclusions, but sibling tool names make the primary distinction apparent, so it meets the threshold for clear context without 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?

Adds substantial behavioral context beyond annotations: draft status (nothing live until publish), one page per waitlist constraint (409 on conflict), headline required, and 'Works on every plan'. These go beyond the simple readOnly/idempotent/destructive hints and do not contradict them.

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?

Four sentences, each earning its place: the core action with draft status, the conflict behavior with alternative, the required field, the plan note, and the tip. Front-loaded with the verb and resource, 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?

Complexity is high (9 params, nested objects) but the schema fully covers parameters. The description covers lifecycle (draft), conflict handling, plan availability, and alternatives. Without an output schema, the 409 conflict and draft/publish behavior are enough to understand the tool's contract.

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 of 3 applies. The description mentions 'headline is required' which is already in schema; it does not add extra semantic details about other parameters. However, since the schema itself is fully descriptive, this 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?

Specific verb+resource: 'Create the waitlist's hosted landing page from structured fields, as a draft'. Clearly distinguishes from siblings (publish_landing_page, update_landing_page, generate_landing_page) by noting one page per waitlist and the 409 conflict, plus the alternative to create_waitlist.

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 tells when not to use: 'returns a 409 error if one already exists (use update_landing_page then)' and provides the tip to use create_waitlist's landing_page parameter when creating both. Also clarifies nothing goes live until publish_landing_page, so the draft-only use case is implied.

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 fully carries the behavioral transparency burden. It discloses authentication (account key), plan limitations (waitlist cap), immediate return values (waitlist key, form_action_url), the draft state of landing pages, and global uniqueness constraints with rejection guidance. This is rich, non-obvious context beyond any structured metadata.

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 about three sentences, front-loaded with the main purpose and return value, then optional parameter behavior, then a crucial uniqueness note. No wasted words; each sentence adds unique 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?

Given the tool's complexity (7 params, nested landing_page object, no output schema), the description provides complete context: it covers return values, plan limitations, authentication, optional landing page behavior, and uniqueness constraints. It doesn't need to explain every parameter because the schema covers them.

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 meaningful semantics on top: it explains that landing_page creates a draft, name and slug must be globally unique, and that the tool returns a form_action_url that collects signups immediately. This boosts the score above baseline.

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 creates a new waitlist on the user's account, with a specific verb and resource. It also distinguishes itself by noting it returns the waitlist key and form_action_url, which is unique among sibling tools like list_waitlists and get_stats.

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 (creating a waitlist) and provides context about account key requirements and plan caps. It mentions that landing pages are provisioned as drafts and that publish_landing_page is needed to go live, but it doesn't explicitly contrast with create_landing_page as an alternative for separate landing page creation.

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 and does so excellently. It discloses that deletion is permanent and irreversible, affects email history, and that counters/queue positions update asynchronously within seconds. It also notes the plan requirement. This is far beyond a generic 'delete' statement.

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 compact—four short sentences, each adding critical information: the operation, irreversibility, async behavior, and plan requirement. There is no filler or repetition. It is front-loaded with the core purpose and then immediately addresses side effects and constraints.

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 tool with no output schema, the description is remarkably complete. It covers what happens to the subscriber and email history, the irreversible nature, the timing of counter updates, and access requirements. It does not need to explain return values since no output schema exists, and the described side effects are sufficient for an agent to anticipate the outcome.

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 both parameters (id_or_email and waitlist_key), so the schema already documents their meaning. The description adds no new parameter-level details beyond what the schema states (e.g., it references 'ID or email' which is already in the schema). Baseline 3 is appropriate since the schema handles parameter semantics.

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 (permanently delete), the target resource (subscriber and their email history), the scope (from a waitlist), and the method (by ID or email address). It distinguishes itself from sibling tools like add_subscriber and update_subscriber by explicitly indicating this is a deletion operation.

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 usage context: use this tool to permanently remove a subscriber. It does not explicitly name alternatives or state when not to use it, but the plan requirement (Growth or higher) provides a clear prerequisite. The purpose is unambiguous enough for an agent to select it appropriately among siblings.

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

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

The description goes far beyond the minimal annotations by disclosing the 1 AI credit cost and balance error behavior, synchronous execution with 20-50 second latency, draft-save outcome, and that the AI conversation is persisted for dashboard continuity. These are critical behavioral traits not available from annotations or schema, making the description highly transparent.

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 dense paragraph that front-loads the primary purpose and then adds necessary behavioral, cost, and workflow details. Every sentence contributes useful information, but the structure could be improved with separation (e.g., bullets) for easier scanning. Still, it remains appropriately concise given the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (AI generation, edit mode, cost, draft state, conversation persistence, sibling relationships), the description covers nearly all relevant aspects. It does not describe the return format or response structure, but with no output schema and a simple success/error model, this is not a critical gap. Overall, it is complete enough for an agent to select and invoke the tool 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 description coverage is 100%, with each parameter already described in detail (e.g., prompt examples, is_edit behavior including 409 error, waitlist_key requirements). The description adds no new parameter semantics beyond mentioning is_edit in context, so it meets the baseline for high schema coverage but does not exceed it.

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 primary function: generating a complete custom landing page from a natural-language prompt using the AI builder, with an optional edit mode via is_edit: true. It distinguishes itself from sibling tools like create_landing_page (non-AI creation) and publish_landing_page (going live), making the purpose 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 provides explicit guidance on when to use this tool (for AI-driven page generation/editing) and when not to (avoid repeated calls for small tweaks that need human review). It also points to alternatives: see update_landing_page for implications of AI-page status and publish_landing_page for going live, giving clear workflow 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?

Beyond the readOnlyHint annotation, the description discloses specific behaviors: the 404 error condition when no page exists, the live URL being null until published, the conditional inclusion of AI credits for AI-built pages, and plan availability. These details meaningfully help the agent anticipate edge cases and response variations.

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 dense but organized: a clear opening verb+resource, a structured enumeration of return content, then a few short sentences adding behavioral caveats. Every clause serves a purpose, though it is slightly longer than strictly necessary compared to the two-sentence ideal.

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 output schema, the description adequately covers the main return fields (status, page_type, copy, theme, SEO, URL, analytics, AI credits), plus error behavior, plan availability, and a link to the create tool. It stops short of specifying formats or additional error cases, but is sufficient 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 schema already provides full documentation for the single waitlist_key parameter (100% coverage), including its optionality and environment variable fallback. The description adds no additional parameter-specific semantics, so the baseline of 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 opens with 'Get the structured view of a waitlist's hosted landing page' — a specific verb+resource+scope. It enumerates the returned fields (status, page_type, copy fields, theme, SEO, URL, analytics), and the distinct read-only verb clearly separates it from siblings like create_landing_page, update_landing_page, publish_landing_page, and generate_landing_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?

The description provides clear context: 'Works on every plan' indicates broad availability, and '404 if the waitlist has no page yet — create one with create_landing_page' names an explicit alternative for the missing-page case. It does not explicitly contrast with other getter tools like get_stats, but the scope of the returned data and the explicit create alternative provide solid usage 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?

Discloses async counter updates (within seconds of signup/delete) and plan availability. Since annotations are absent, this provides useful behavioral context about freshness and accessibility, though it doesn't cover error cases or output format.

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 concise sentences: first states purpose and value, second discloses a key behavioral trait. No fluff, 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?

For a simple read-only stats tool with 1 optional param, the description covers what it does and an important behavior (async updates). Since no output schema exists, it could mention return format, but the description's mention of counters implies basic numeric values. Overall 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 already documents waitlist_key thoroughly (optional, format, source). The description adds no additional parameter insight, but with 100% schema coverage, baseline 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?

Clear verb+resource: 'Get a waitlist's subscriber and view counters'. Distinguishes from sibling get_subscriber by focusing on aggregate counters, and from list_subscribers by returning counts rather than subscriber details.

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?

Indicates this is for social proof counters, implying it's the right tool for quick stats rather than detailed subscriber lists. Mentions it works on every plan, establishing availability, but doesn't 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?

With no annotations, the description carries the burden of behavioral disclosure. It mentions the access requirement (Growth plan or higher) and enumerates the types of data returned (position, points, referral info, metadata, location). However, it does not explicitly state that this is a read-only operation that does not modify subscriber data, nor does it describe error behaviors (e.g., what happens if no subscriber matches). This is adequate but not fully transparent.

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 at two sentences, with the primary action and parameters in the first sentence and the plan requirement in the second. It is front-loaded with the key information and contains no redundant or extraneous words. Every sentence contributes to understanding the tool's purpose and constraints.

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 tool with two parameters and no output schema, the description covers the essential information: what it does, what data it returns, and the plan requirement. It lacks explicit error semantics or a note about read-only nature, but given the schema handles parameter details and the tool is a straightforward retrieval operation, it is fairly complete. A small gap is the absence of mention of return type or structure, but the listed fields give a good indication.

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 provides a 100% description coverage for both parameters, so the baseline is 3. The description adds minimal semantic value by mentioning 'by their ID or email address', which aligns with id_or_email, but it does not add any new detail about waitlist_key. The schema handles parameter explanations well, so no penalty, but no bonus 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 action ('Retrieve detailed information about a specific subscriber'), the target resource (subscriber), and the lookup method (by ID or email). It distinguishes itself from sibling tools like list_subscribers (which lists all subscribers) and get_stats (which returns statistics), making the 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 provides clear context for when to use this tool: when you need detailed information for a single subscriber identified by ID or email. It also notes the plan requirement (Growth plan or higher), which is a prerequisite. However, it does not explicitly mention alternatives or when not to use it compared to list_subscribers, but the 'specific subscriber' wording implies the contrast.

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 provides useful behavioral details: pagination, sortability, and the Growth plan requirement. It does not disclose rate limits or response format, but for a read-only list tool, it covers key operational aspects.

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, tightly worded sentence that front-loads the core action and key capabilities. Every word adds value, with no redundancy or 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?

The description gives a high-level overview but omits response structure details (no output schema exists) and does not mention the optional waitlist_key fallback behavior or pagination defaults. It is adequate for a simple list tool but leaves some operational 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 100% for all 5 parameters, each with descriptions, enums, and defaults. The tool description only lists sortable fields already present in the schema enum, adding no new semantic information beyond what the schema 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 the tool retrieves a paginated list of a waitlist's subscribers and specifies sortable fields. It distinguishes from sibling tools like list_waitlists by focusing on subscribers rather than waitlists, and from get_subscriber by being a list operation.

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 for fetching subscriber lists and notes a plan requirement (Growth or higher), which is a usage condition. It does not explicitly mention alternatives or exclusions, but the context is clear enough for basic 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?

No annotations are provided, so the description must carry the burden of behavioral disclosure. It discloses a required account key for authentication and indicates the return includes counts. However, it does not mention potential limitations like pagination, rate limits, or error behavior, which would be valuable for a list operation. The description covers some traits but lacks depth.

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 the action, scope, and key output details without any filler. Every word contributes meaning, making it highly concise and well-structured.

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 list tool with no parameters and no output schema, the description adequately covers the purpose, authentication requirement, and return contents (subscriber and view counts). It does not explain the output structure in detail, but since there is no output schema, the description's mention of counts fulfills the core need. Minor gaps like missing pagination details prevent a perfect score.

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 zero parameters, so the baseline for this dimension is 4. The description adds no parameter-specific meaning because there are none to describe, which is appropriate given the tool takes no input.

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 'List' and identifies the resource as 'every waitlist your account owns', with the added detail of 'subscriber and view counts' that clarifies the expected output. This clearly distinguishes it from sibling tools like create_waitlist and get_stats, which serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context that this is for listing all waitlists owned by the account, implying it is the go-to for an overview. It does not explicitly mention alternatives or when not to use it, but the 'every waitlist your account owns' phrasing provides sufficient contextual guidance for a tool with no parameters.

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 disclosure burden. It conveys the core action and purpose but does not detail side effects, idempotency, or required setup beyond what the schema covers. This is minimal but not misleading.

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, front-loaded with the action, and contains no filler. It efficiently conveys the purpose and use case 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?

As a simple logging tool with well-described schema parameters, the description provides essential context: what it does and when to use it. It doesn't explain return values (no output schema) or relationships to get_stats, but these are not necessary for basic invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The tool description does not add parameter semantics beyond the schema; the schema itself already explains parameters well (e.g., visitor_id prevents duplicate counts).

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 records a waitlist page view, using a specific verb 'Record a view' and resource 'waitlist page'. It distinguishes itself from sibling tools like add_subscriber or create_waitlist, and adds context by mentioning tracking engagement and conversion rates.

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 a clear context for when to use the tool: when hosting your own landing page and wanting to track engagement/conversion. It does not explicitly name alternatives or exclusions, but the use case is distinct from other waitlist tools.

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 (readOnly=false, idempotent=true, destructive=false), the description discloses important behavioral nuances: validation requirements (email field, submit button, headline length), the automatic generation of OG images when publishing from the dashboard versus skipping it via API, and that it works on every plan. This adds significant value beyond the structured 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 concise, using three sentences to cover the main action, alternative behavior, validation criteria, and the social-image caveat. Information is front-loaded with the primary purpose at the start, and every sentence contributes unique value without unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no output schema and only two optional parameters, the description covers the essential behavioral aspects: URL targeting, unpublish capability, validation checks, image behavior, and plan support. It does not mention return values or error handling, but for a simple publish action, the completeness is adequate, though not exhaustive.

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 covers both parameters fully (unpublish and waitlist_key), so the baseline is 3. The description adds meaning by explaining the effect of 'unpublish: true' (takes the page offline) and implies which parameter is used for publishing vs unpublishing. This goes slightly beyond the schema's description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: publishing a landing page to its live URL or unpublishing it. It specifies the exact URL format (waitlister.me/p/{slug} or custom domain) and distinguishes from sibling tools like get_landing_page or update_landing_page by focusing on the publish/unpublish 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 for when to use the tool, including the ability to unpublish with 'unpublish: true'. It also mentions validation criteria that must be met for publishing to succeed, which guides usage decisions. However, it does not explicitly name alternative tools or state 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?

Discloses significant behavioral traits beyond annotations: changes go live immediately on published pages, AI-built pages return 409 for copy/structure fields, and theme/seo work on both page types. The idempotentHint annotation is complemented by 'Update any subset' suggesting partial updates are safe, but the live-publishing and error behavior are valuable additions.

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?

Though the description is dense, it is well structured and every sentence earns its place: first states the core action, then live-publishing behavior, then the critical AI-page exception, and finally plan coverage. No wasted 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?

Given the tool has 9 parameters, nested objects, and no output schema, the description covers the key contexts: partial updates, immediate live effect, AI-page limitations, and plan availability. It provides enough information for an agent to select and invoke the tool correctly, including the crucial edit-path alternative.

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 baseline is 3. The description adds value by grouping parameters into 'copy/structure fields' (headline, description, button_text, collect_name, collect_phone, background) vs 'theme and seo,' which directly informs which parameters are restricted on AI pages. This is extra semantic context not present 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 opens with 'Update any subset of the landing page's structured fields,' a specific verb+resource statement. It also distinguishes from sibling tools by explicitly naming generate_landing_page and noting that theme and seo still work for AI-built pages, while copy/structure fields do not.

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 explicit when-to-use guidance: for AI-built pages, copy/structure fields should be edited via generate_landing_page with is_edit:true, while theme and seo remain editable here. Also states 'Works on every plan,' removing plan-based ambiguity.

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 transparency burden. It discloses a notable side-effect ('updating points triggers a queue position recalculation') and the partial-update behavior ('Only include fields you want to change'), which are valuable non-obvious details. It does not cover return values or error handling, but the key behavioral traits are present.

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 redundancy, front-loaded with the core action. Every sentence provides useful information: the action, the partial-update guideline, a side-effect, and a plan requirement. Zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no output schema, the description covers essential context: what can be updated, partial-update semantics, a non-obvious side-effect, and a plan restriction. The schema fully documents parameters, so the description is reasonably complete. It could mention the return value or error behavior, but those omissions do not significantly hinder tool selection.

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. The description adds the general rule 'Only include fields you want to change' and flags the points recalculation, but individual parameter meanings are already fully described in the schema. The description does not need to compensate for schema gaps.

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 explicit verb 'Update' and specifies the exact resources and fields (name, phone, points, custom metadata). It clearly differentiates from sibling tools like add_subscriber, get_subscriber, and delete_subscriber by targeting existing subscribers.

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 use: 'Only include fields you want to change' indicates partial updates, and 'Requires the Growth plan or higher' sets a prerequisite. It does not explicitly name alternative tools, but the 'existing subscriber' phrasing and sibling names make the intended use clear.

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