asksteps

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds meaningful behavioral details beyond that: the file is analysed in memory and NOT stored, problems are reported as status values rather than errors, and a scan yields status 'no_fillable_fields'. This informs the agent about privacy expectations and error handling.

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?

Six sentences with no filler. The core purpose comes first, then usage guidance, input handling, privacy note, limitation, and status behavior. Every sentence earns its place and the structure is logical.

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

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

A read-only analysis tool with strong annotations and an output schema. The description covers input alternatives, privacy, limitations, and result handling. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so parameters are already documented. The description adds the critical rule that exactly one of pdf_url or pdf_base64 must be passed, and explains why URL is preferred (base64 makes the message huge). This is useful semantic guidance 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 opens with a specific verb and resource: 'Analyses a fillable PDF form and reports its fields, pages and whether asksteps can digitise it.' It clearly distinguishes the tool from generic analysis or import tools by focusing on digitisation feasibility for the user's own document, going beyond a generic yes/no.

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 explicit usage context: 'Use this when someone asks whether their own PDF form, application or contract could become an online form.' It also clarifies input constraints ('Pass exactly one of pdf_url or pdf_base64') and the limitation to fillable PDFs, though it does not name alternative tools for non-fillable scans.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false, so the description carries the burden of explaining side effects. It adds crucial behavior: wiring does not publish, the operation requires publish:write, invalid subdomain names produce a list of valid ones, and no DNS records or certificates are created. This is beyond what annotations or the schema 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?

The description is dense but every sentence earns its place: core action, permission, exclusion boundary, failure behavior, and required next step. It is front-loaded and avoids 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?

Given the output schema exists and annotations cover safety, the description is complete for invocation: it covers prerequisites, invalid-input behavior, and the follow-up call. Nothing needed to use this tool correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters well. The description still adds meaning by emphasizing that the subdomain must already be held by the account and that the path is chosen by the caller. This is helpful context beyond the schema descriptions.

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 a clear verb and resource ('Wires a form to one of the subdomains the account ALREADY holds') and immediately scopes what it does not do: it 'does NOT create a subdomain or a domain.' This distinguishes it from domain-creation and publication tools without ambiguity.

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 states the required permission ('Requires "publish:write"'), gives explicit failure-handling guidance ('read those out instead of guessing'), and names the required follow-up tool ('afterwards call asksteps_publish_form with target "whitelabel"'). It also warns that domain creation is outside this tool's responsibility.

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 annotations: it warns "THIS SPENDS THE CUSTOMER'S MONEY," discloses the dry-run first call returning confirmation_required + net price, the downgrade side effect (features can switch off), the mandatory email to the owner, and the checkout_required edge case. None of this contradicts the annotations (readOnlyHint=false and idempotentHint=true are consistent with a two-phase charged mutation).

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 highest-stakes warning (spends money) is front-loaded in the second sentence, followed by prerequisites, the two-step protocol, caveats, and edge cases in logical order. Though longer than average, every sentence carries operational weight for a financial mutation with a confirmation flow — there is no filler or repetition of schema content.

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 an output schema exists to cover return values, the description covers everything an agent needs to call correctly: prerequisites, the two-phase confirmation flow, downgrade caveats, the first-purchase/ch checkout_required edge case, and owner notification. Nothing needed to avoid a harmful financial mis-call is missing.

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

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

Schema description coverage is 100%, and the schema already gives rich per-parameter guidance (e.g., confirm: "Set to true only AFTER you told the user the price and they agreed"). The description reinforces the confirm protocol at workflow level but adds no per-parameter meaning beyond the schema, 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 first sentence, "Moves an account that already pays to a different plan," is a specific verb (moves) + resource (paid account → plan). The qualifier "already pays" actively distinguishes it from first-purchase flows, and the description reinforces this boundary with the checkout_required edge case, so an agent can tell it apart from siblings like asksteps_start_checkout without opening their schemas.

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 an explicit protocol (first call never changes anything, read the confirmation_required price, get agreement, then call with confirm=true), explicit prerequisites (billing:write, account owner, purchase mandate with max plan/spending cap/expiry), and an explicit when-not boundary ("a first purchase is not something an agent can complete"). It also warns that downgrades need mandate allowance. This is full when/when-not 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?

Beyond the annotations, the description adds valuable behavioral context: the link opens in the builder, no account is needed to view it, it does not write into anyone's account, a human always saves it, and the returned URL must be given verbatim. It also explains the rejection behavior and what to do after a failed call.

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 front-loaded with the core purpose and then provides dense, non-redundant guidance on usage, behavioral implications, failure handling, and alternatives. Every sentence adds actionable information without 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 complexity of the nested spec schema and the presence of an output schema, the description covers all necessary context: when to call, what happens after the call, how to handle the returned link, rejection recovery, and the crucial no-account side effect. Nothing important is missing.

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

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

Schema description coverage is 100%, and the spec parameter is thoroughly documented in the input schema. The tool description adds context about the workflow but does not need to repeat parameter details, so the baseline score 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 first sentence states a specific action ('Turns a form you have designed with the user into a draft') and a concrete output ('returns a link'). It clearly distinguishes this tool from siblings like asksteps_create_form by emphasizing the draft-and-human-save workflow rather than direct account writes.

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 says when to use it ('once you and the user agree on what the form should ask'), gives a clear when-not case ('For digitising an existing PDF, do not rebuild it here'), and names the alternative ('Point the user at the PDF import in the product instead'). It also covers the rejection retry flow.

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 significant behavior beyond annotations: the 'forms:write' permission requirement, the critical fact that the form is created but NOT published (ownership of publishing stays with the account owner), and the silent-incompleteness trap of reconstructing PDFs from partial analysis. No contradiction with annotations (readOnlyHint=false aligns with 'Creates').

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 with zero waste. The core purpose leads, the permission requirement and non-publish behavior follow immediately, and the PDF caveat closes with an actionable alternative. 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?

Exceptionally complete for a complex nested-object tool: purpose, permission, publication state, and a subtle data-integrity trap are all covered, and an output schema relieves the description of return-value explanations. The only minor gap is that the sibling asksteps_import_pdf exists but isn't named as the programmatic alternative to 'tell the user to import it in the studio', which would have been more directly actionable for the agent.

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

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

Schema coverage is 100% and the schema itself is exceptionally detailed, describing every property with types, examples, and field-type semantics. The description adds only a high-level paraphrase ('from a structure of steps and fields'), so the baseline 3 applies — the schema does the heavy lifting.

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

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

States a specific verb ('Creates'), a specific resource ('a new form in the connected asksteps account'), and the input structure ('from a structure of steps and fields'). It differentiates from siblings by explicitly warning against using it to rebuild a PDF from asksteps_analyze_pdf output, making its scope unmistakable.

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

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

Gives explicit when-not-to-use guidance: 'Do not use this to rebuild a PDF', names the sibling tool involved (asksteps_analyze_pdf), explains why (silently incomplete copy), and redirects the user to the correct alternative (import in the asksteps studio). This is explicit routing with rationale, not just implication.

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

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

Annotations only carry false hints (not read-only, not idempotent, not destructive), so the description carries the behavioral burden. It adds three valuable disclosures: the created resource "is NOT published", it "Requires forms:write", and the template's design/success page/wording are inherited. This enriches the annotation surface without contradicting it.

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 with a distinct job: purpose, permission, usage guidance, and publication state. The core action is front-loaded and no sentence is filler or redundant with the schema.

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 only 2 parameters, an output schema documenting return values, and full parameter coverage, the description covers everything needed to invoke correctly: what it does, when to prefer it, prerequisite call, follow-up call, permission, and resulting state. Nothing essential is missing for an agent to use it safely and 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 both parameters are already fully documented and the baseline of 3 applies. The description reinforces that template_id comes from asksteps_list_templates, but that fact already appears in the schema, so it adds little new semantic meaning beyond the structured data.

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?

"Creates a form or funnel from one of the ready-made templates" pairs a specific verb and resource with a distinct creation path, immediately separating it from asksteps_create_form and asksteps_create_funnel, which build from scratch. The added detail about inheriting design, success page and wording further pins down what this tool uniquely accomplishes versus its siblings.

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?

"PREFER THIS over building from scratch when a template fits" explicitly states when to select this tool over alternatives and why: it carries design, success page and wording that the plain structure cannot describe. It also chains a complete workflow — call asksteps_list_templates first, then refine with asksteps_update_form — leaving nothing to inference.

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

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

Annotations are all negative hints (not read-only, not idempotent, not open-world, not destructive), so they reveal little beyond 'this is a mutation.' The description adds genuinely useful behavioral context: the required scope "forms:write" and the crucial lifecycle fact that the funnel is created but not published — publishing requires a separate step. This prevents the agent from wrongly assuming the funnel goes live. No contradiction with annotations. It stops short of a 5 by not covering edge behaviors like duplicate-name handling or whether the result is a draft.

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?

Six sentences, each earning its place: purpose, required scope, sibling routing, ref/target construction model, start-point rule, and publication state. The core definition is front-loaded and there is zero filler or repetition of schema content. It is dense but structured so an agent can parse it quickly.

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 — a deeply nested spec with nodes, answers, targets, screens, and settings — the description covers the semantic gaps the schema cannot: branching direction, target vocabulary, start point, auth scope, and the not-published state. The output schema covers return values, and the 100% schema coverage covers field details. Minor gaps keep it from 5: it does not cross-reference the publish sibling tool by name, nor clarify that existing funnels should be edited via asksteps_update_funnel.

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 per-field burden is already carried by the schema — baseline 3. The description adds above-baseline value by explaining the wiring model that the schema's individual field docs don't convey: refs are short jump targets, answer targets can be 'next'/'success'/'dismiss'/another ref, and 'the first question in the list is where the funnel starts.' This explains the relationships between parameters rather than just their types.

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 a specific verb and resource: 'Creates a conversational funnel in the connected asksteps account', then defines the core mechanism ('one question at a time, where each answer decides what comes next'). It explicitly differentiates from the closest sibling, asksteps_create_form, by naming the distinguishing conditions (different follow-up questions, ruling someone out part-way). An agent can reliably tell this tool apart without opening the schema.

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

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

The description gives explicit when-to-use guidance: 'Use this instead of asksteps_create_form when answers should lead to DIFFERENT follow-up questions, or when someone should be able to be ruled out part-way through.' This names the alternative, the selection conditions, and — by implication — when not to use this tool. It also sets expectations for the downstream workflow ('NOT published; publishing is a separate step').

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 (destructiveHint=true), the description discloses critical behavioral traits: the two-call confirmation protocol, the confirmation_required response with submission count, the permission requirement, and irreversibility ('This cannot be undone'). These details are not present in the annotations and add substantial safety-relevant 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?

Three tight sentences cover the action, prerequisite, the two-call protocol, and irreversibility. Every sentence earns its place; no filler or redundancy. The most critical safety detail (first call never deletes) is front-loaded after the action statement.

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 destructive nature and the output schema availability, the description fully covers the prerequisites, the required user-confirmation workflow, and the irreversible consequence. An agent has everything needed to invoke the tool correctly and safely.

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 operational meaning to the confirm parameter by explaining the two-call sequence and when to set confirm to true, complementing the schema's own parameter description. form_id is straightforwardly covered by 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 ('Deletes') and clearly identifies the resource ('a form or funnel from the connected account') along with the scope ('together with every submission it has collected'). This unambiguously distinguishes it from sibling tools like asksteps_update_form or asksteps_publish_form.

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 operational guidance: requires 'forms:write', first call never deletes, must read the confirmation count to the user, and only call again with confirm = true. It does not explicitly name alternative tools or state when not to use it, but the delete context is clear enough that no closer alternative exists 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?

Annotations already indicate a safe, idempotent read operation. The description adds meaningful behavioral context: prices are net, the vatNote field controls how they should be treated, and gross prices should not be computed without it. This goes 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?

Three sentences front-load the core purpose, then provide usage timing and a critical pricing caveat. There is no filler and each sentence contributes essential guidance.

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?

An output schema exists, so return values are covered. The description supplies the missing context: when to invoke this first, what it answers in one call, and how to handle the vatNote and net prices. For a simple one-parameter discovery tool, nothing essential is missing.

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

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

There is only one optional parameter, locale, and the input schema already documents it fully with an example and default. The description does not need to add parameter-level detail, 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 clearly states what the tool returns: asksteps overview, bookable plans with net prices, and quota key meanings. It names a specific verb and resource, and it distinguishes itself from the sibling tools by being the planning/information endpoint rather than a CRUD or workflow tool.

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

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

The description gives explicit 'call this FIRST' guidance and specifies the triggering questions: whether asksteps fits a use case, what it costs, or before creating anything. It does not name alternative tools or give when-not-to-use conditions, but the context is clear enough for an agent to route correctly.

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 and idempotentHint annotations, the description explains the read is a prerequisite for safe updates, discloses the auth requirement ('forms:read'), and reveals that the response includes an 'editable' field indicating whether writing is allowed. This is valuable behavioral context that helps the agent understand side effects and sequencing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: the first defines what is read, the second gives a mandatory usage rule and why, and the third adds a relevant behavioral detail. No filler or repetition of schema/annotation content.

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 read tool with an output schema and read/idempotent annotations, the description covers the essential context: what is returned, permission needed, why it must precede updates, and the editable flag. There are no critical gaps for an agent to discover at call time.

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 full coverage for the single parameter, form_id, including its provenance from asksteps_list_forms. The description does not add parameter-level detail, so the baseline of 3 is appropriate since the schema carries the semantic weight.

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

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

States a specific verb and resource: 'Reads one form ... as a structure of steps and fields.' The phrase 'the same shape asksteps_update_form takes' distinguishes this read tool from other asksteps tools and clarifies its role in the update flow. The title reinforces the read-only, editable-structure purpose.

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 explicit, actionable usage guidance: 'ALWAYS call this before asksteps_update_form: the write replaces the whole form, so you need the current state to keep what you are not changing.' It also names the required permission. However, it does not explicitly state when not to use this tool or contrast it with sibling read tools such as asksteps_get_form_stats or asksteps_get_funnel.

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 and idempotentHint, and the description adds the required permission scope and the fact that stats are for a published form. It does not contradict annotations and provides useful behavioral context beyond the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler. The core behavior, permission requirement, and prerequisite are all front-loaded, making it easy for an agent to parse quickly.

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 a full output schema and complete parameter documentation, the description covers authentication, the prerequisite id source, and the returned metrics. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description mostly restates the publication_id source that the schema already documents. It adds no new parameter-level detail beyond reinforcing that the id comes from asksteps_list_forms.

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 ('Returns') and names the exact resource ('visits, completions and drop-off for one published form'), which clearly distinguishes this stats tool from sibling tools like asksteps_get_form or asksteps_list_forms. The title reinforces the purpose without ambiguity.

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 actionable usage guidance: it requires the 'forms:read' scope and tells the agent to obtain the publication_id from asksteps_list_forms first. It does not explicitly contrast with alternatives, but the prerequisite and resource naming make the intended call path clear.

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, openWorldHint=false. The description adds the prerequisite forms:read scope, the branching behavior, and the flat-form fallback behavior. It aligns with annotations and adds useful context beyond 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?

The description is compact, front-loads the main purpose, and the guidance about the write replacement is placed prominently. Some redundancy with the title exists, but each 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?

The tool has one required parameter fully documented, strong read-only annotations, an output schema exists, and the description covers the fallback to asksteps_get_form. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the one parameter is clearly described as the funnel id from asksteps_list_forms. The description doesn't add much beyond the schema, but there is little need. Inline schema descriptions are complete so 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?

The title and description clearly state the tool reads one funnel and its branching (questions, answers, where each answer leads). It distinguishes from the sibling asksteps_get_form by noting that if the id is a flat form the response says so and points to the correct tool.

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

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

Explicitly instructs to ALWAYS call this before asksteps_update_funnel because the write replaces every question, and explains how to handle the case where the id is a flat form by pointing to asksteps_get_form. This is strong when-to-use and alternative guidance.

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

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

Annotations already mark the tool as readOnly and idempotent, and the description goes beyond them by disclosing the required 'billing:read' permission, the trial-time discrepancy between effectivePlanCode and planCode, and the meaning of the 'mandate' field. This is rich, actionable behavioral context not present in 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 compact yet information-dense. The primary return value is front-loaded, followed by the permission requirement, the main use case, a critical interpretation trap, and the mandate field. 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 empty input schema, rich annotations, and presence of an output schema, the description covers everything an agent needs: what is returned, required permission, when to call it, how to interpret the response correctly, and whether plan changes are permitted. There are no meaningful 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?

The tool has zero parameters and the input schema is empty, so there is no parameter burden for the description to carry. The baseline for zero-parameter tools is 4, and the description appropriately avoids inventing parameter guidance that would be irrelevant.

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 names a specific verb ('Returns') and a precise resource: the connected account's plan, trial state, and usage quotas. It also clarifies the mandate field, making it easy to distinguish from sibling tools like asksteps_get_capabilities or asksteps_change_plan.

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 a clear trigger condition: 'Call this whenever something was refused for a limit — it answers why can I not do this in one call.' It also warns about reading effectivePlanCode instead of planCode during trials. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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

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

The description adds substantial context beyond the annotations: it requires 'pdf:write', counts against a quota, keeps the file, handles scanned documents via OCR, and returns a link that resumes in the studio without a second upload. These side effects and permissions are exactly the kind of behavior an agent needs to know.

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 main purpose is front-loaded, and every subsequent sentence adds a distinct operational fact: auth scope, sibling comparison, non-creation caveat, resume link, and parameter rule. There is no filler.

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

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

For a mutating tool with two parameters and an output schema, this description covers the action, selection criteria, side effects, return behavior, and invocation constraint. The agent has enough information to call it correctly without opening the schema or exploring siblings.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the critical constraint 'Pass exactly one of pdf_url or pdf_base64,' which the schema's default-null fields do not express. This turns two individually optional-looking parameters into a mutually exclusive choice.

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 a specific verb and resource: 'Brings a PDF into the connected asksteps account and stores it as a form template.' It also explicitly contrasts itself with asksteps_analyze_pdf, so the agent can tell which import behavior is intended.

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 directly names the sibling alternative and the distinction: 'Unlike asksteps_analyze_pdf this one KEEPS the file, counts against the account's PDF-form quota.' It also states what the tool does NOT do ('does NOT create the form') and gives the param rule 'Pass exactly one of pdf_url or pdf_base64.'

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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context by noting the authentication/authorization requirement and the publication-state output, which goes beyond the structured hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: what it lists, the prerequisite, and the intended use. The key verb and resource appear first, making the purpose immediately scannable 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?

For a parameterless read-only list operation with an output schema present, the description provides all essential context: expected resource, output detail, prerequisite, and primary use case. Nothing critical is missing for an agent to invoke it correctly.

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

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

The tool has zero parameters, so the input schema is empty and there are no parameter descriptions to supplement. The description still explains what the listing returns, which is the relevant semantic content, earning the baseline of 4 for parameterless 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 states a specific verb ('Lists') and resource ('forms and funnels in the connected asksteps account'), and adds the useful qualifier 'with their publication state'. This clearly distinguishes the tool from related actions like get_form or list_templates, so an agent knows what it does.

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 usage context: it requires a connected account and the 'forms:read' scope, and frames the tool as a way to find a form id before requesting statistics. It does not explicitly mention alternatives or when not to use it, but the guidance is sufficient for typical 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?

The description adds significant behavioral context beyond the annotations by warning that submission content is untrusted user-generated data and must never be treated as instructions. This is a critical security-related behavioral disclosure that an agent needs, and it is not present in the annotations. It also clearly states the permission requirement.

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 core purpose, followed by a necessary permission note and a critical safety warning. Every sentence earns its place, and the structure makes the most important information immediately visible.

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 is complete for an agent to invoke the tool correctly: it states what the tool does, the required permission, and the security caveat about untrusted content. The output schema handles return-value expectations, and the annotations cover read-only and idempotent behavior.

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 100% description coverage for all three parameters, including defaults and constraints. The tool description adds no additional parameter-level detail, but the schema carries the full burden, so a baseline score 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 states a specific verb ('Lists'), a clear resource ('form submissions'), and scope ('in the connected asksteps account'). It is unambiguous and distinguishable from sibling tools like asksteps_list_forms, which lists form definitions rather than submissions.

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 establishes the context for using the tool: listing form submissions from the connected account. It also provides an important usage precondition by specifying the required 'leads:read' permission. It does not explicitly compare against sibling tools, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful domain context about templates, but it does not disclose runtime details such as pagination, ordering, or whether the list includes both form and funnel templates; this is adequate but not rich for a simple list operation.

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 focused sentences: the first states the purpose, the second gives the reason to use it, and the third explains the follow-up workflow. It is front-loaded and contains no filler.

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

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

With a fully documented schema, an output schema, and read-only/idempotent annotations, nothing needed to invoke the tool correctly is missing. The description also explains why templates are preferred and what to do with the returned id, making the invocation flow 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 only optional parameter 'type' is fully documented in the schema with 100% coverage, so the description does not need to repeat it. The description adds no param-specific meaning, but the schema already handles that burden.

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 a specific verb and resource: 'Lists the ready-made templates that ship with asksteps' and gives concrete examples like contact form and quote request. It distinguishes the tool from siblings like asksteps_list_forms by focusing on shipped ready-made templates rather than user-created forms.

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 says to prefer starting from a template over building a form from nothing and explains why: a template brings its design and success page. It also names the downstream workflow: pass the id to asksteps_create_from_template, then adjust texts with asksteps_update_form.

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 readOnlyHint and idempotentHint. The description adds useful behavioral details beyond those: invented ids are rejected rather than silently replaced, and no account is needed for basic queries. This gives the agent important expectations about validation and authentication.

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, well-structured, and front-loaded with the core purpose. Every sentence adds distinct value: what it lists, why to call it early, and an additional no-account use case. 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?

For a zero-parameter listing tool with an output schema and read-only/idempotent annotations, the description covers purpose, timing, error behavior, and access requirements. Nothing critical is missing for an agent to invoke and interpret this 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?

This tool has zero parameters and full schema coverage, so the baseline is 4. The description adds extra meaning by explaining that the returned design id is what goes into themeId, which helps the agent use the output correctly in downstream calls.

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 ('Lists') and clear resource ('ready-made designs a form or funnel can use'), and connects the output to the themeId field. It clearly differentiates this from sibling tools like list_forms or list_templates by focusing on theme/design options.

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 instructs when to call it ('Call it before you set a design') and warns about invalid ids being rejected. It does not explicitly mention alternatives or when not to use it, but the guidance is clear and actionable for an 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?

The description adds substantial behavioral context beyond the annotations: the 'publish:write' requirement, the meaning of statuses, the warning never to invent slugs, the legal implications of publishing publicly, and the unconditional behavior of publish=false. No contradiction with the idempotentHint=true annotation is 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?

The description is dense but every sentence earns its place, covering purpose, status handling, agent guidance, and warnings. It is front-loaded with the core publish-or-return-link behavior, then systematically adds necessary guardrails without 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?

Even with a rich schema and annotations, the description covers all critical operational details: authorization failure, statuses, required user interaction, slug safety, legal notice, and offline behavior. An agent has enough to call the tool correctly across the main scenarios.

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 guidance on top: 'never make one up' for slug, 'Set to true only AFTER the user has explicitly agreed' for confirm, and repeated emphasis to ask the user. This elevates the value beyond the schema alone.

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 states a specific verb and resource ('Publishes a form or funnel') and immediately differentiates the alternate outcome when the account lacks authorization. This clearly distinguishes the tool's purpose from siblings like asksteps_update_publication.

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 conditional guidance: what to do on 'confirmation_required', 'input_required', and 'published' statuses, and notes that taking offline always works without mandate. It does not explicitly name alternative sibling tools for comparison, but the conditional workflow is strong enough 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 mark this as read-only and idempotent, and the description adds valuable behavioral context: it returns passages with URLs, and crucially, it clarifies that an empty result is not necessarily a failure and that a note field distinguishes the cases. This goes beyond the schema and 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 three sentences with no filler: it states the action, explains the purpose, and addresses the empty-result edge case. Every sentence adds information and the most important guidance is front-loaded.

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

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

With only two parameters, a high-coverage schema, an output schema, and annotations for read-only and idempotent behavior, the description provides everything an agent needs to call this tool correctly. It even resolves a subtle ambiguity about empty results that would otherwise be easy to misread.

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 parameter descriptions already fully document both 'query' and 'locale'. The description provides an example query but does not add extra semantic explanation beyond what the schema already gives, so the baseline score 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 a specific verb ('Searches'), a resource ('the public asksteps website'), and the output ('matching passages with their URLs'). It also provides the intended use cases, making it obvious this is a documentation-search tool rather than a CRUD operation on forms or funnels.

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 tells the agent when to use it: to quote or cite what the product does and to check whether a feature exists. It also explains how to interpret an empty result, saying it likely means the feature is absent rather than that the search failed, which is crucial practical 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?

Even though annotations already indicate readOnly/idempotent, the description adds critical non-obvious context: no purchase happens, the customer pays the provider directly, asksteps never sees card data, and the statutory acknowledgement must be given personally. No contradiction with annotations; 'Requires billing:write' is a permission requirement, not a claim that the call mutates state.

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 main result is front-loaded in the first sentence, followed by permission, side-effect clarification, and routing to the sibling. Every sentence adds value, and the payment caveats justify the length.

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 an output schema present, all parameters fully described in the schema, rich annotations, and explicit sibling routing, nothing is missing for an agent to select and invoke this 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 schema already documents plan_code and interval. The description adds that plan_code determines the preselected plan, but no new parameter-level detail beyond the schema is needed.

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 states a specific verb and resource: 'Returns the link where the user books a plan themselves, with that plan preselected, and the exact net price.' It immediately distinguishes itself from asksteps_change_plan, so the agent can tell what this tool is for without relying on the title.

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 explicitly states when to use ('Use this for a FIRST purchase') and when not to ('To move an existing paid account between plans, use asksteps_change_plan instead'), plus the 'billing:write' requirement. This is unambiguous selection 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?

The description discloses the critical destructive behavior: every step and field not sent is deleted. It also reveals that the publication state is never changed and that unsupported forms are refused with an explanation. These go well beyond the annotations, which only indicate non-read-only and idempotent behavior. 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 compact and every sentence earns its place: purpose, permission, destructive warning, required workflow, refusal conditions, and publication-state guarantee. Critical information is front-loaded, and there is no filler or repetition of trivial schema details.

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 complex tool with nested objects and an output schema, the description covers all essential operational context: permissions, destructive semantics, the prerequisite get-then-update workflow, refusal cases, and what remains unaffected. The output schema handles return-value details, so nothing important is missing.

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

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

The input schema already provides 100% coverage with detailed descriptions for every parameter, including nested field types, defaults, and constraints. The description adds no parameter-specific meaning, but with such thorough schema documentation, a baseline of 3 is appropriate. The description does reinforce the 'anything omitted is deleted' concept, but the schema already states this.

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 states a specific action ('Replaces an existing form') and identifies the exact resource ('of the connected asksteps account'). It clearly distinguishes this from creating a new form and emphasizes the whole-form replacement semantics. No ambiguity about what the tool does.

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 explicit usage guidance: call asksteps_get_form first, modify what the user asked for, and send the complete result back. It states the required permission ('forms:write') and names important exclusions (PDF-based forms and unsupported elements are refused). This is strong when-to-use guidance that complements the sibling 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?

Annotations already include destructiveHint=true and readOnlyHint=false, but the description goes further by spelling out the destructive consequence ('every question you leave out is gone'), what is preserved ('Design, settings and the end pages are NOT touched unless you include them'), and the required 'forms:write' scope.

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?

Every sentence earns its place: purpose, permission, required pre-read, destructive warning, preserved surfaces, and refusal conditions. The most important information is front-loaded.

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

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

Given the very large nested spec object, the description is remarkably complete operationally: it states the prerequisite read, the destructive behavior, what is preserved, the required permission, and refusal cases. Return value is covered by the output schema.

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 schema already provides rich per-parameter explanations. The tool description mostly restates the replacement semantics already present in the schema rather than adding new parameter-level meaning.

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 a specific verb+resource pair: 'Replaces the questions and the branching of an existing funnel.' It also clarifies scope by saying design, settings, and end pages are untouched unless included, which helps distinguish this from other update tools.

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?

Clear context and exclusions: it instructs to read the funnel first with asksteps_get_funnel, warns that omitted questions are removed, and states that PDF-built funnels are refused. However, it does not explicitly name alternative sibling tools or conditions for preferring them.

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 annotations, the description adds concrete behavioral details: a form without a page returns 'not_found', renaming keeps the old address as a redirect, and nothing new goes online. These details cover failure modes and side effects without contradicting the idempotentHint or destructiveHint 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 five sentences with no filler; the core purpose is front-loaded and every sentence adds operational value. It avoids restating schema boilerplate while still covering permissions, error behavior, and side effects.

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 and parameter descriptions cover 100% of inputs, the description provides all essential operational context: prerequisites, required permission, error condition, side effect, and user-communication guidance. Nothing material is missing for correct tool selection and 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 coverage is 100%, so the schema already documents all parameters clearly, including empty-string password removal and visibility values. The description adds extra meaning for the slug parameter by explaining that renaming keeps the old address as a redirect and that the user should be consulted before changing 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 first sentence names a specific verb ('changes') and resource ('public address (slug), who may find it, or page password') of a form that is already published. It clearly distinguishes this tool from asksteps_publish_form by scoping it to already-published forms.

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 says to use this tool when the form is already published and directs users to asksteps_publish_form first when no page exists. It also states the required 'publish:write' permission and instructs the agent to ask the user before changing a slug, giving clear when-to-use and 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.