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?

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and the description meaningfully extends them: it clarifies that the tool does not write into anyone's account because a human always saves the draft, and that the returned URL must be handed over verbatim. It does not disclose the non-idempotent behavior (each call presumably yields a new draft) or any auth requirements.

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?

Front-loads the action and return value, then when-to-use, then caveats and error recovery. Nearly every sentence carries operational value. The one soft spot is the rhetorical clause "it is the step that turns the conversation into something they can actually use", which is flavour rather than instruction.

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 single-parameter tool with a large nested schema and an output schema, the description covers the remaining burden well: what is produced, that no account write occurs, how to hand off the URL, when not to use it, and how to recover from rejection. Nothing an agent needs in order 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 description coverage is 100% across the deeply nested spec object, so the schema already carries all field-level meaning. The description adds no guidance about the spec shape beyond restating that it is "a form you have designed", which lands at the baseline for a fully documented schema.

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

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

States a specific verb and resource: it turns an agreed form spec into a draft and returns a link, and adds that opening the link shows it in the asksteps builder. That is concrete and distinguishable from read/list siblings. It does not, however, clarify how this differs from asksteps_create_form or asksteps_create_funnel, which an agent would likely weigh against it.

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

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

Gives a clear trigger ("once you and the user agree on what the form should ask") plus a genuine exclusion with a redirect ("For digitising an existing PDF, do not rebuild it here... Point the user at the PDF import"). It also covers the retry loop after rejection. The gap is that it never contrasts with the sibling asksteps_create_form, so the agent must guess which creation path applies.

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 cover safety flags (readOnly=false, openWorld=false, idempotent=false); the description goes well beyond them by disclosing the required 'forms:write' scope, the partial side effect (created but not published), and a concrete data-integrity warning about silently incomplete PDF rebuilds. These are the details an agent needs to avoid a harmful call, and they are not derivable from 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?

Four sentences, front-loaded with the action, then auth requirement, then publishing state, then the anti-pattern. Every sentence earns its place and the most decision-relevant facts come first.

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, return values need no explanation, and the description still covers auth, publication state, and a PDF misuse case. The one notable gap is that it never states the non-idempotent behavior (repeated calls create duplicate forms), which the annotations imply but the prose does not.

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

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

Schema description coverage is 100% and the single 'spec' object is exhaustively documented down to nested field types, so the schema carries the load. The description only frames 'spec' as 'a structure of steps and fields' and adds no syntax, ordering, or validation detail beyond it — the correct baseline of 3.

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 ('Creates a new form in the connected asksteps account') plus the input shape ('from a structure of steps and fields'). It also carves out a distinct niche versus siblings such as asksteps_analyze_pdf and (implicitly) asksteps_import_pdf, so an agent can route correctly without opening 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?

Gives an explicit when-not: do not use it to rebuild a PDF, because asksteps_analyze_pdf only surfaces part of the document, and instead direct the user to the asksteps studio import. It also clarifies the follow-up state ('NOT published — publishing stays with the person who owns the account'), steering the agent away from assuming publication. It stops short of naming asksteps_publish_form or asksteps_import_pdf as the concrete alternatives.

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?

Goes beyond the annotations by disclosing the required scope ("forms:write") and the post-creation state ("It is NOT published; publishing is a separate step"), which an agent needs to know. It does not mention rate limits or return shape, but the annotations plus these additions cover the main behavioral questions for a non-destructive create.

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?

Front-loaded with purpose and the sibling routing, then the structural rules, then the publication caveat. Every sentence carries information, though the ref/target sentence is somewhat dense and partly restates schema text.

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

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

Given a rich nested schema, an output schema, and annotations, the description covers what matters: scope requirement, non-publication, and how questions/answers/targets wire together. An agent could call this correctly without further guidance.

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 a usable mental model: give every question a short ref, point each answer's target at another ref/"next"/"success"/"dismiss", and the first question is the start. This wiring explanation helps the agent construct a valid spec even though the schema repeats most of 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?

Specific verb (creates) plus resource (a conversational branching funnel) with the defining behavior stated up front: one question at a time where each answer decides what comes next. This clearly distinguishes it from asksteps_create_form, the sibling it shares a resource family with.

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 names the alternative tool (asksteps_create_form) and the two conditions that select this one: when answers should lead to DIFFERENT follow-up questions, or when a respondent can be ruled out part-way through. That is a genuine when-to-use/when-to-use-the-other rule.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds value beyond that: it requires the forms:read permission, warns that the write is a full replacement (hence the read-first mandate), and notes the returned editable flag that gates whether writing is allowed. That goes well past what annotations supply.

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-loaded with purpose then the read-before-write rule. No filler, though the pipe-dash phrasing is slightly dense; still efficient overall.

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?

Output schema exists, so return values needn't be fully explained, yet the description still names the editable flag and the steps/fields shape. Combined with the read permission and the write-replacement warning, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the sole parameter form_id is documented as coming from asksteps_list_forms, so the baseline is satisfied. The description adds meaning by framing the output shape (steps and fields) and the editable field, though it says nothing new about the single input parameter.

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 (reads) and resource (one form), and describes the shape returned (steps and fields), explicitly tying it to the sibling asksteps_update_form's expected shape. This distinguishes it clearly from asksteps_list_forms and asksteps_get_form_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?

Gives an explicit rule: ALWAYS call this before asksteps_update_form, and explains why (the write replaces the whole form, so you need current state). That is a concrete when-to-use constraint with reasoning, not vague 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 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 only cover the safety profile (readOnlyHint, idempotentHint); the description adds the required scope ('Requires "forms:read"'), the read-before-write workflow dependency, and the degraded-input behavior when the id is a flat form. That is meaningful context beyond what the annotations declare.

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, zero filler, front-loaded with purpose then constraints then fallback. Each sentence changes agent behavior.

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 need no elaboration, yet the description still outlines the returned branching. Auth scope, prerequisite ordering, and the wrong-resource fallback all covered — nothing needed to invoke 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% for the single funnel_id, so the schema already carries the baseline. The description adds value by warning that the id may actually refer to a flat form and what happens then, which clarifies the parameter's real-world semantics beyond the schema note.

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 funnel') plus the returned substance ('questions, answers and where each answer leads'), which immediately separates it from asksteps_get_form and asksteps_list_forms. An agent can identify the tool's job 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?

Gives an explicit ordering rule ('ALWAYS call this before asksteps_update_funnel') with the reason (the write replaces every question), and names the alternative for the wrong-id case ('points you at asksteps_get_form'). When-to-use, when-not, and alternatives are all present.

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?

Annotations only cover readOnlyHint=false, idempotentHint=true and openWorldHint=false; the description adds what actually matters here: that every step/field not sent is destroyed, that "forms:write" is required, that certain forms are refused with a reason, and that publication state is untouched. That is substantive context the structured fields do not carry.

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?

Five tight sentences, front-loaded with the highest-risk fact (full replacement), then workflow, then refusal behavior, then the publication caveat. No sentence is redundant with the title or 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?

For a deeply nested, destructive mutation with an output schema, the description supplies the missing pieces: destructive scope, permission requirement, recommended read-before-write workflow, and refusal/preservation behavior. Nothing an agent needs to call it correctly is absent.

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 nested spec structure is already fully documented field by field, including that omitted content is deleted. The description reinforces the "complete document" nature of spec but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Replaces an existing form") plus scope ("of the connected asksteps account"), which cleanly separates it from asksteps_create_form and asksteps_update_funnel. The destructive whole-form semantics are stated up front rather than buried.

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

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

Gives an explicit prerequisite workflow — "Call asksteps_get_form first, change what the user asked for, and send the result back complete" — which names the sibling to read with. It also states rejection conditions (PDF-built forms, undescribable elements). It does not explicitly contrast with asksteps_create_form for new forms, so it falls just short of full when/when-not coverage.

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 flag destructiveHint=true and idempotentHint=true, but the description goes well beyond them: it discloses the write permission needed ('forms:write'), the destructive replacement model ('every question you leave out is gone'), the untouched surface area, and the refusal conditions. This is exactly the extra context a full-replacement mutation needs.

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, front-loaded: what it does, the permission, the required read-first procedure, the blast radius, then the failure modes. No sentence is redundant with another and none is 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 destructive, deeply nested mutation the description covers purpose, auth, precondition, blast radius, and refusal handling, and it points to 'the answer says which' for refusals. With an output schema present, return-value detail is appropriately omitted.

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 tree is exhaustively documented, including 'Everything not included is removed', so the description is not required to carry parameter meaning. The description reinforces the spec replacement semantics ('send back everything you want to keep') but adds nothing the schema does not already state. Baseline 3 applies.

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

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

The description gives a precise verb and resource: 'Replaces the questions and the branching of an existing funnel', and immediately scopes it further by listing what is NOT replaced (design, settings, end pages). That scope statement is what separates it from asksteps_update_form and asksteps_create_funnel without the agent needing to open any 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?

It names the prerequisite tool and the exact procedure: 'READ IT FIRST with asksteps_get_funnel and send back everything you want to keep'. It also states the conditions under which the call is refused (PDF-built funnels, formats it cannot describe), so an agent knows when to route elsewhere or expect failure.

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.