Formstep

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

Annotations only declare it as a non-read-only, non-destructive, closed-world write. The description adds far more: bytes never pass through this tool, the upload URL expires in one hour, the Content-Type must match the declared value, and the upload is verified downstream by request_create. These are exactly the behavioral traits an agent cannot infer from the 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?

Front-loaded with the action and the return contract, followed by the byte-transfer workflow in one dense sentence. No filler; the closing load_skill pointer is the only non-essential clause but is useful routing.

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

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

With no output schema, the description still enumerates the return fields ({ id, uploadUrl, expiresAt, name, contentType, size }) and the full follow-up workflow, including the downstream verification step. Nothing needed to call 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 baseline is 3. The description goes further by linking contentType to the subsequent PUT ('with the declared Content-Type') and implying formId scopes the upload. It doesn't clarify size/sha256 semantics beyond the schema, so it's above baseline but not exhaustive.

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: 'Reserve an upload for one document a request hands to its recipient through the form's Documents block.' This clearly separates it from siblings like editor_insertDocumentsBlock (which edits the form) and request_create (which consumes the document), so an agent can route 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 the full ordering constraint explicitly: PUT the raw bytes to `uploadUrl`, then pass { documentId: id } in request_create's `documents`. It also names the condition that makes reuse safe ('one upload serves any number of requests') and points to load_skill("requests") for the higher-level 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered; the description adds genuinely new behavioral context — the last user-facing element cannot be deleted and the auto-managed submit button is excluded from the count. It omits error behavior for invalid nodeIds and whether deletion is reversible.

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 tight sentences, front-loading the action first and the sourcing constraint and deletion limit second. Nothing is redundant or padded.

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 two-parameter destructive tool with no output schema, the description covers the key agent decision points: where to get nodeId and the one deletion guardrail. It could say more about failure modes or response, but nothing essential for correct invocation 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 only 50% (formId has a description, nodeId has none), so the description must compensate — and it does, telling the agent exactly where nodeId comes from and warning against fabricating it. formId itself gets no additional detail, but that is a minor gap.

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 ('Delete an element from the form') and clearly separates itself from the surrounding insert/update siblings by describing removal of an existing node. An agent can select it 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 a concrete precondition and workflow: obtain nodeId from a fresh editor_getDocument response rather than guessing. It does not explicitly name editor_updateElement as the alternative for modifying rather than removing, so the when-not side is left implicit.

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=false, destructiveHint=false, and openWorldHint=false. The description adds useful scope (link wraps matched substring; color applies to highlight/underline) but does not explain auth needs, match-failure behavior, or what removal changes.

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 operation, then compactly lists formats and color constraints. Every clause earns its place; there is 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 an 8-parameter mutation tool with no output schema, the description covers formats and some parameter meaning. It remains incomplete on node targeting, occurrence semantics, and link URL requirements, though annotations cover the safety profile.

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 63%, and the description clarifies the action apply/remove and color scope beyond the enum. However, it omits nodeId, occurrence behavior, and the link URL requirement, with some of those details already present only in the schema.

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

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

States a specific verb pair (apply/remove) and resource (text formatting), then enumerates the exact supported formats. This lets an agent distinguish it from editor_insert* and editor_updateElement siblings 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?

The description implies usage through 'apply or remove' and the format list, but gives no explicit when-to-use, prerequisites, or alternative-tool routing. An agent can infer the context, but guidance is not spelled out.

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, so 'Read-only' adds little, but the description goes beyond them by describing the return structure (content plus an idRoles map with role labels) and pointing to load_skill("toon-format") for the payload schema, which is valuable since no output schema exists.

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 tightly packed sentences that front-load the core purpose and then layer usage and payload guidance. Only the redundant 'Read-only' clause fails to earn its place against the annotations.

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 no-output-schema read tool this covers purpose, ordering constraints, and the shape of the result with a pointer to skill documentation. It falls short only on parameter semantics, which both schema and description leave bare.

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 0% and the description never mentions either parameter: no explanation of what formId identifies, nor that version selects draft vs published (an enum with a default). The heavy lifting the schema cannot do is left undone.

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 ('Read the form document as a TOON-serialized tree') and describes the returned payload (content + an idRoles map labelling node ids by logic role). This clearly distinguishes it from siblings like form_get or the many editor_insert* authoring 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?

Gives explicit timing and ordering: 'consult before authoring logic' and 'Use before any editor_insert*/update/replace/delete to discover nodeIds.' The agent knows both why and when to call this ahead of the mutation 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?

Beyond the annotations, the description discloses important runtime behavior: validation happens with AI while the respondent fills in the form, a note appears when answers do not fit, submission is still allowed, and the result is stored at data.aiValidations.<key>. It also explains the ordering dependency created by reading preceding questions and hidden 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?

The description is compact and front-loaded: it states what is inserted, how it behaves, the ordering requirement, and the result path in four efficient sentences. Every sentence adds useful information and there is no wasted text.

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

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

With no output schema, the description helpfully states the runtime result path, and it explains the key ordering dependency. It does not cover failure modes or the full return value of the insert operation, but annotations and the rich input schema cover most other needs.

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 carries detailed parameter meaning. The description adds conceptual context about the sentence and key result path, but it does not materially explain individual parameters such as formId, parentId, position, or after beyond what the schema provides.

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

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

The description states a specific verb and resource: inserting an AI Validation sentence that checks named answers with AI while the respondent fills in the form. This is clearly distinct from sibling insert tools such as logic, calculated fields, or question inserters because the unique validation behavior is explained.

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 gives a concrete placement rule: insert it after the last question it reads because it reads questions above it and hidden fields. That is clear usage context, but it does not explicitly compare this tool against alternatives such as editor_insertLogic or explain when not to use it.

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

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

Annotations already declare it is a non-read-only, non-destructive, closed-world mutation, so the bar is lowered. The description adds genuinely new behavioral context: the field is hidden from respondents and is designed to be driven by calculateValue logic rules, which the annotations do not convey.

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 tightly packed sentences: purpose first, then visibility, then the driving action, then an example, then the sibling alternative. Every sentence earns its place with 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 seven-parameter mutation tool with no output schema, the description covers purpose, intended workflow, and the key sibling boundary. It omits what the call returns (e.g. the created node/field ID), which an agent inserting-then-chaining would benefit from, but otherwise 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?

Schema description coverage is 100%, so the schema already documents all seven parameters thoroughly (including chaining via $prev and position/after incompatibility). The description adds a naming example and the fieldType-in-practice hint, but does not meaningfully extend parameter semantics beyond the schema.

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

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

Specific verb+resource ('Insert a calculated field') plus the concrete use cases (scoring, counters, computed runtime values) make the tool's role unmistakable. It explicitly distinguishes itself from the sibling editor_insertHiddenField, so an agent can route correctly without opening either 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?

States when to use it (with the calculateValue action in logic rules), gives a worked example ('Total Score' field accumulating points), and names the alternative for URL-seeded metadata. This is explicit when/when-not/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 declare this is a non-read-only, non-destructive write, so the safety profile is covered. The description's main behavioral claim, "Requires 1+ options," merely restates the schema's minItems constraint and adds no new mutation context. No mention of ordering effects or side effects on existing nodes.

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 short, front-loaded sentences with zero filler. The core purpose and the key usage condition lead, and no sentence is redundant.

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

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

For a mutation tool with full schema coverage and clear annotations, the definition supplies enough to act on. The absence of output-schema detail is acceptable, though the description could note insertion/ordering caveats that the schema only partially conveys.

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 all 12 parameters are already documented in the schema (including the subtle 'after' vs 'position' semantics and the required-default). The description adds no parameter detail beyond the "1+ options" restatement, which is the baseline 3 case.

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 specific verb and resource ("Insert a checkbox question") and frames it as "multi-choice selection," which separates it from single-choice siblings like editor_insertRadioQuestion. It does not explicitly name the contrasting sibling, so the differentiation must be inferred from "multi-choice."

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?

"Use when user can pick multiple" gives a clear condition for selecting this tool over its alternatives. It stops short of naming the sibling to use for single-choice cases, so the exclusion is only implied.

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

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

Annotations already declare a non-read-only, non-destructive, non-open-world write operation, so the safety profile is covered. The description adds no behavioral context beyond that – it says nothing about what node is created, what is returned, permissions, or the interaction of after/position (which the schema handles). For a mutation tool it contributes almost no disclosure.

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, correctly front-loaded with the action and resource. The second sentence is low-value filler rather than an operational constraint, but overall there is no bloat.

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 schema is very rich (14 params, enums, nested object, insertion-position constraints), so the description needn't restate parameters, and no output schema exists to explain. However, for a complex insertion tool it omits any note on the created node's identity or return value, leaving it minimally adequate.

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 documents all 14 parameters and the nested defaultValueFieldRef object, including mutual-exclusivity notes (after vs position, defaultValue vs defaultValueFieldRef). The description only lightly echoes contactType semantics, 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 description gives a specific verb+resource ('Insert a contact question') and enumerates the domain (email, phone, URL), so an agent can distinguish it from other editor_insert*Question siblings without opening the schema. It stops short of explicitly naming the alternatives it is not (e.g., insertTextQuestion) for a truly differentiated 5.

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?

'Choose contactType based on what information you need' is guidance about parameter choice, not about when to prefer this tool over the other insert-question tools. There is no when-to-use/when-not statement or named alternative, so usage is only implied.

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

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

Annotations already state readOnlyHint=false, destructiveHint=false, openWorldHint=false, giving the safety profile. The description adds no further behavioral context (such as ordering behavior, side effects, or required permissions) beyond the one-sentence purpose, so it contributes little beyond the annotations.

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

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

The description is a single grammatical sentence with no filler, but for a 9-parameter insertion tool it is arguably too terse and does not front-load any operational guidance. It is concise but under-specified for the tool's complexity.

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

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

Given 9 parameters, many sibling tools that insert other question types, and no output schema, the description is not complete enough. It fails to help the agent distinguish this tool from other insert-question tools or understand when to use it, though annotations and schema cover safety and parameters.

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 all 9 parameters are documented in the schema itself. The description adds no parameter-level information, leaving the schema to carry the full semantic load; 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 description names a specific verb ('Insert') and resource ('date picker question'), making the tool's function clear. It does not differentiate from sibling insert-question tools (e.g., insertTimeQuestion, insertScheduleAppointmentQuestion), so it stops short of a 5.

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

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

No when-to-use guidance, no prerequisites, and no alternatives are mentioned. The agent receives no help choosing this tool over other question-insertion 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 disclose the safe-mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds a genuine behavioral fact the annotations cannot: this element is what actually sets a request's outcome, which matters for choosing it. It does not cover revert/positioning side effects, which the schema handles.

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 tightly written sentences, front-loaded with the action and the distinguishing semantic, with zero filler. The radio contrast is placed last as a routing hint.

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

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

For a mutation tool with no output schema, the description conveys the essential semantic (outcome-setting decision question) and the schema carries the rich positional/nesting detail at 100% coverage. It lacks guidance on placement or chaining, but the schema's after/position descriptions cover that.

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 all 8 parameters, including the labels object and the after/position chaining rules. The description adds no parameter detail beyond restating the label values, 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?

States a specific verb and resource ('Insert the decision question ... that sets a request's outcome') and nails the disambiguating trait of the three option labels (approve/decline/changes). It implicitly separates itself from editor_insertRadioQuestion by noting a plain radio never sets an outcome.

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 clause 'A plain radio never sets an outcome' tells the agent when this tool is the right choice over the radio-question sibling, which is the key routing decision among the many insert_* tools. It stops short of an explicit 'use X instead' or stating prerequisites, so it is clear context without full exclusions.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description need not restate them. It adds genuinely useful behavior beyond the annotations: the block 'collects no answer' and files are added elsewhere, preventing a misinterpretation of the write operation. It stops short of covering insert semantics like chaining/ordering, hence 4.

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 tight sentences, front-loaded with the action and resource, with zero filler. The 'not here' caveat earns its place by preventing a wrong assumption about file loading.

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

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

With no output schema, annotations carrying the safety profile, and a fully documented parameter schema, the description covers the non-obvious essentials: what the block is and what it does not do. A brief note on insertion ordering would round it out, but 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%, and the schema already explains the tricky interactions (after vs. position, $prev chaining, parentId scoping). The description adds no parameter-level detail and none is needed. 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?

States the specific verb+resource ('Insert a Documents block') and immediately defines the resource: 'a download list of files (PDF, images) the owner hands to the respondent.' The clause 'Collects no answer' distinguishes it from sibling tools like editor_insertFileQuestion, so an agent can tell them apart without opening either 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 gives a clear scope boundary — 'files are added in the editor, not here' — telling the agent that this tool only places the block and does not populate it. It also conveys the use-case (a non-answering download list) versus answering question blocks. However, it does not explicitly name the alternative tool or state exclusion conditions, so a 4 rather than 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?

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds a meaningful non-schema behavioral constraint (never guess a source; ask the user), which prevents a whole class of bad calls, though it says nothing about ordering conflicts or error behavior on a bad URL.

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

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

Two sentences, zero padding: purpose first, then the critical constraint. Nothing repeats the schema or annotations.

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 6-parameter mutation tool with no output schema, the description covers purpose and the key input-integrity rule, and the schema carries full parameter detail. It stops short of noting anything about the result of insertion or failure handling, but nothing essential for correct invocation 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%, including the after/parentId/position interplay and provider semantics, so the baseline is 3. The description's provider examples ('youtube for videos, google-maps for maps, iframe for third-party embeds') largely restate the enum descriptions already in the schema, adding little beyond 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 ('Insert') plus resource ('embedded content') and enumerated subtypes (YouTube video, Google Maps location, iframe embed). An agent can distinguish this from sibling inserters like editor_insertImage or editor_insertDocumentsBlock 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 a strong operative rule — use a real user-provided source URL and ask the user rather than fabricating one. That is clear when-to-use guidance for the main failure mode, though it names no alternative sibling tools (e.g. editor_insertImage) for adjacent cases.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the mutation/safety profile is covered structurally, but the description adds no behavioral context at all. It omits the risks its own schema hints at, such as the default of required=true and that omitting 'after' appends to the end (called out as 'usually wrong').

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, front-loaded with the verb and resource, with no filler. It is efficient, though it restates the tool title almost verbatim rather than spending the words on something the agent lacks.

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 an 11-parameter mutation tool with no output schema, the description is thin: it never addresses placement semantics (after vs position vs parentId) or defaults, which is where an agent is most likely to err. Complete enough to invoke via the schema, but it does not cover the failure modes the schema itself flags.

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 every one of the 11 parameters is already documented, including the accept pattern and maxSize units. The description's mention of accepted file types and size limits merely paraphrases two schema fields and adds no syntax, default, or interaction detail beyond them.

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?

Names a specific verb and resource (insert a file upload question), which is enough to separate it from the many other editor_insert* question-type siblings. However, it does not explicitly contrast with adjacent question types such as picture choice or signature, so the differentiation rests on the noun alone.

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

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

No when-to-use, prerequisites, or alternatives are given. Nothing tells the agent whether a form must already exist, whether it should be called before or after other inserts, or which sibling to reach for when a non-file question is intended.

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 declare it is a non-read-only, non-destructive write. The description adds real behavioral context beyond that: the level cannot be changed after insert and editor_updateElement supports only isHidden, required, titleIsHidden. This tells the agent about immutability and the mutation surface, which the annotations do not.

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, no filler, and the core action and level semantics are front-loaded. The trailing parenthetical listing supported props is dense but earns its place by scoping the later update path.

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 7-param write tool with full schema coverage and annotations, the description covers the ambiguity-prone parts (level meaning, immutability) even though it does not address ordering behavior. Nothing critical for a correct 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 coverage is 100% so the baseline is 3, but the description adds meaning the schema lacks: that level 1 = largest, and that the level argument is locked at insert time. That is genuine semantic value, though positioning params (after/parentId/position) are left entirely to 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?

States a specific verb+resource: 'Insert a heading element.' That is unambiguous and distinct from sibling insert tools like editor_insertParagraph. It stops short of explicitly naming which sibling to prefer, but the resource is precise enough for selection.

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?

Explains how to pick a header size (level 1-4, 1 = largest) and warns the level is frozen, which subtly signals 'get it right the first time.' However, it never states when to choose this over editor_insertParagraph or other insert tools, so usage is implied rather than spelled out.

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, openWorldHint=false, confirming a non-destructive write confined to the form. The description adds useful behavioral context — the field is seeded from URL params and submitted with the form, and is referenceable in defaultValueFieldRef, logic conditions, and calculateValue refs. It doesn't cover ordering side effects (after vs position), idempotency, or what happens to existing fields. With annotations present the bar is lower, so a 3 is fair.

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

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

Two sentences, front-loaded with the core action and then the intended use cases. It is appropriately sized for the tool and has no filler. The second sentence is dense but each element (URL params, defaultValueFieldRef, logic conditions, calculateValue) is meaningful.

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 write tool with no output schema, the description covers purpose and the referenceable-value behavior, but omits the insertion-position nuance (after vs position cannot be combined) which is critical to correct invocation. The sibling differentiation is also absent, leaving an agent to choose between editor_insertVariable, editor_insertCalculatedField, and this tool without explicit 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 description coverage is 100%, so all six parameters already carry descriptions, including the positional 'after'/'position' semantics and the paramName pattern. The description adds no additional parameter detail beyond this. Baseline 3 applies when 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 ('insert') and resource ('hidden metadata field'), and goes beyond by naming use cases (URL param seeding, form submission). It doesn't explicitly differentiate from siblings like editor_insertVariable or editor_insertCalculatedField, which have overlapping roles for referenceable values, leaving some 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 a purpose and example use cases ('recipient IDs, campaign tags, attribution data') but does not state when to prefer this over editor_insertVariable or editor_insertCalculatedField, which are the closest functional siblings. An agent still has to infer the choice.

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 this is a non-destructive, non-open-world write, so safety is partly covered. The description adds a substantive rule beyond the annotations — never fabricate stock/placeholder/Unsplash URLs and instead prompt the user — which genuinely shapes agent behavior. It does not mention permissions or insertion side effects, keeping it below a 5.

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

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

Three sentences, front-loaded with the action followed by the sourcing constraint. The second and third sentences overlap somewhat (avoid inventing URLs / ask the user for a real image), so it is slightly more verbose than strictly necessary.

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 an 11-parameter insert tool with no output schema, the description covers purpose and the critical behavioral guard, while the schema covers all parameters. Nothing essential is missing, though positioning/return expectations are left entirely to the 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% across all 11 parameters, and the schema itself carries strong semantics (e.g., 'after' noting that omission is 'usually wrong', 'position' enum semantics). The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

The description opens with a specific verb+resource ('Insert an image element'), so an agent immediately knows the operation. It does not explicitly contrast itself with nearby siblings like editor_insertPictureChoiceQuestion or editor_insertEmbedded, but the resource is distinct enough that confusion is unlikely.

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 gives clear preconditions for use ('a user uploaded' image or 'a URL the user explicitly provided') and an explicit negative case (no real image → ask the user to upload or paste a URL). It stops short of naming alternative tools, but the when-to-use guidance is concrete.

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 this is a non-destructive, non-open-world write, so the safety profile is covered. The description adds nothing behavioral beyond that — no note about insertion ordering, required placement, or what happens on insert — so it contributes almost no context the annotations don't 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?

Two short sentences with zero filler, and the core purpose is front-loaded before the use-case hint. Nothing wastes the agent's context budget.

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 an 11-parameter insertion tool with no output schema, the annotations and rich schema cover the mechanics, and the description is technically sufficient to call it. It is nevertheless thin on the one thing that matters here: disambiguating this tool from the many other insert*Question 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 description coverage is 100% and all 11 parameters (min, max, after, position, parentId, isHidden, labels) are documented inline in the schema itself. The description adds no parameter-level meaning, 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 ('Insert a linear scale question') and gives concrete range examples (1-5, 1-10), which is more than a restatement of the title. However, it never distinguishes itself from the very similar sibling editor_insertRatingQuestion or editor_insertNumberQuestion, so an agent must guess between them.

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?

'Use for sentiment, agreement scales' implies a context but gives no when-not and no comparison to the near-identical rating/number question tools in the sibling list. The guidance is only implicitly useful.

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 a non-destructive, non-readOnly, closed-world write, so the safety profile is covered. The description adds that 'items' is a native string array and shows a concrete payload, but says nothing about what is returned, whether insertion is atomic, or how placement interacts with later chaining.

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 short sentences, front-loaded with the purpose, then variant semantics, then a compact example. Nothing is wasted, though the inline example slightly duplicates what the schema type already conveys.

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 6-parameter write tool with no output schema, the description covers purpose, variant semantics, and payload shape, while placement semantics (after/parentId/position) are fully handled by schema descriptions. The main omission is any hint of the return value (e.g., the new node id), which an agent may need for follow-up inserts.

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 3 is the baseline, and the description actually adds real value: the schema only says variant is 'List type', while the description explains ordered=numbered vs unordered=bullets, and it clarifies that items is a native array rather than an encoded string. The worked example makes the required combination unambiguous.

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 concrete verb+resource ('Insert a list element') that is immediately distinguishable from the many sibling insert tools (paragraph, table, question types). It does not, however, explicitly name which sibling to prefer or contrast with, so it stops short of 5.

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 conditional guidance given ('ordered' for numbered, 'unordered' for bullets) is about parameter choice, not about when to choose this tool over editor_insertParagraph, editor_insertTable, or other insert siblings. Usage is implied by the name and example rather than stated.

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

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

Annotations cover the safety profile (non-read-only, non-destructive, closed world), and the description adds genuinely non-obvious behavioral context: that a show action requires isHidden:true on the target or it stays visible in the editor baseline. This is real value beyond the structured fields, though other mutation traits (permissions, ordering) are not covered.

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 front-loaded sentences with no filler: purpose and cardinality first, then the actionable show/isHidden caveat, then a skill pointer. The final sentence could arguably be tighter, but every sentence carries information.

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, annotation-backed mutation tool with no output schema, the description covers the critical gotcha and the per-call granularity. It correctly defers deep rule semantics to the referenced skill rather than duplicating the 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% with rich nested descriptions, so the baseline is 3. The description reinforces the one-rule-per-call constraint on 'rule' but adds no syntax or format detail beyond what the schema already provides.

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

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

The description states a specific verb (Insert) and resource (one logic element containing exactly one conditional rule), and clarifies the cardinality constraint that additional rules need separate elements. It does not name the obvious sibling alternatives (editor_setLogic, editor_testLogic), so it misses full sibling differentiation.

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

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

It gives an implied usage pattern ('insert separate logic elements for additional rules') and a conditional caveat for show actions, but never states when to reach for this tool versus editor_setLogic or editor_testLogic. The load_skill pointer defers guidance elsewhere rather than providing it inline.

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 this a non-read-only, non-destructive, closed-world write, so the safety profile is covered. The description adds the useful input constraint that rows/columns must be native arrays and never a JSON string, but says nothing about insertion placement behavior, auth, or side effects beyond what annotations provide.

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

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

Three sentences, front-loaded with the purpose before the usage note and format constraint. The example is somewhat long for an inline snippet but directly reduces malformed calls, so it earns its place.

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

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

For an 11-parameter insertion tool with full schema coverage, no output schema, and pre-populated annotations, the description covers purpose, use case, and the highest-risk input format pitfall. Placement semantics are left entirely to the schema, which is a minor gap.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description earns extra credit by calling out the native-array requirement for rows/columns and providing a concrete payload example. It does not clarify the placement parameters (after/position/parentId), which remain schema-only.

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 ('Insert a matrix/grid question') and adds a scope note ('rating multiple items on the same scale') that separates it from editor_insertRatingQuestion and editor_insertRadioQuestion. It does not name siblings explicitly, so it stays short of a 5.

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?

'Use when rating multiple items on the same scale' gives a clear use context. It lacks any when-not guidance or explicit pointer to the alternative question types an agent might confuse it with, but the context is unambiguous.

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=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds no behavioral context beyond the annotations – nothing about insertion ordering (after/position), the default required=true, or what happens to existing nodes. It essentially repeats feature names.

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 tight sentences, front-loaded with the core action. No wasted text, though it is thin enough that it doesn't earn a 5 for information density.

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 13-parameter tool with nested objects and no output schema, the description is minimal. Because schema coverage is 100%, the parameters themselves are well documented, so the definition is adequate but does not cover the behavioral complexity of insertion ordering and defaults.

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 all 13 parameters, including the tricky insertion-ordering semantics of 'after' and 'position'. The description's mention of min/max/step is redundant with the schema, so the 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?

States a specific verb and resource ('Insert a number question') and clarifies the input domain ('for numeric input'), which distinguishes it from the many sibling insert*Question tools. It's clear but doesn't explicitly contrast against alternatives like text or rating questions.

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

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

No when-to-use or when-not guidance is given. With dozens of sibling question-insertion tools, the agent gets no help deciding between this and insertTextQuestion, insertRatingQuestion, etc. 'Supports min/max bounds and step increments' describes features, not selection 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?

With annotations covering the safety profile (readOnlyHint=false, destructiveHint=false), the description adds substantial non-obvious behavior: a submit-button is automatically prepended, the form retains its trailing submit-button, and multi-page forms having one submit-button per page is expected rather than duplication. It also clarifies the divider is not a container and only holds a name label.

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 purpose is front-loaded in the first sentence, followed by critical usage constraints and behavioral gotchas in a logical sequence. Despite being longer than a one-liner, every sentence conveys a distinct instruction or warning relevant to correct invocation.

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

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

Given the tool's complexity, the 100% schema coverage, and the absence of an output schema, the description is complete enough. It covers the key structural and sequencing gotchas an agent needs without needing to explain return values.

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 all six parameters. The description still adds meaningful semantic constraints beyond the schema: isThankYouPage must be true for thank-you pages, parentId must not be set to the divider, and after should reference the last content node of the page being closed.

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 ('Insert a page divider'), explains the resulting structure ('split the form into multiple pages'), and distinguishes the divider from content-insertion siblings by clarifying it is a flat break marker, not a container. An agent can identify the tool's role without opening sibling 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?

It gives explicit when-to-use guidance ('For a post-submit thank-you page, ALWAYS pass isThankYouPage: true'), explains how to add page content (separate inserts using after, chaining via $prev), and names the wrong approach to avoid ('never by passing parentId = the divider'). It also specifies after = id of the last content node.

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=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that — no note on where the node lands, that insertion mutates the form, or any post-insert behavior or ordering caveat. With the lower bar set by annotations, this still adds no behavioral context.

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

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

A single front-loaded sentence with zero padding. It is efficient, though the brevity borders on under-specification rather than true conciseness given the tool's six parameters.

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

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

For a mutation tool with no output schema, the description is thin — it omits any note that insertion is positional within a form, that content supports rich markup, or that the node can be created hidden as a show-rule target. Most of that is recoverable from the rich schema, but the description alone is only minimally adequate.

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 fully documents formId, content, after, parentId, position, and isHidden, including the $prev chaining and markup syntax. The description contributes no additional parameter meaning, so the baseline 3 applies.

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

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

The description states a specific verb+resource ('Insert a paragraph element') and adds a scope qualifier ('for descriptive text'), which distinguishes it from the many question-insertion siblings. It stops short of explicitly differentiating itself in the family of editor_insert* tools, but the resource is unambiguous.

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

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

There is no when-to-use guidance, no mention of prerequisites (e.g., needing a formId in edit mode), and no reference to alternatives like editor_insertTextQuestion or editor_updateElement. Any routing signal lives entirely in the schema, not the description.

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 cover the safety profile (readOnly=false, destructive=false), and the description adds genuinely useful behavioral context: the element can be inserted without a Stripe connection but will not process payments until connected. It does not describe the return value or insertion failure modes, but with annotations present this is solid added 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 short sentences, front-loaded with the purpose, then usage, then the key constraint and example. No filler and nothing misplaced.

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 9-parameter insert tool with full schema coverage and no output schema, the description covers purpose, trigger, the critical Stripe dependency, and a syntax example. Only a note on what the tool returns or on sibling routing would make it fully complete.

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

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

Schema coverage is 100%, so the schema already documents all nine parameters, including amount units and currency format. The description's example ({amount:25, currency:"usd"}) is a helpful convenience but largely restates what the schema provides, so the 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 description opens with a specific verb+resource ('Insert a payment question') and immediately scopes it with the scenario ('collect a payment at submit time'). It is clearly distinguishable from the many sibling editor_insert*Question tools by naming the exact element type.

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 gives an explicit trigger ('Use when the form must collect a payment at submit time') and concrete examples (tickets, fees, orders), plus the Stripe prerequisite. It stops short of stating when NOT to use it or naming a specific alternative tool, so it falls just below the top band.

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 write (readOnlyHint=false), non-destructive, closed-world. The description adds genuinely new behavioral guidance beyond that: images must come from user uploads or provided URLs, and the anti-hallucination constraint "never invent or guess image URLs." It doesn't cover permissions or how insertion placement behaves, keeping it at 4.

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 tightly packed sentences: purpose, when-to-use, a minimal example, and a constraint. Front-loaded and free of filler; the example is compact and the final sentence earns its place as a safety rule.

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 12-parameter insertion tool with full schema coverage, no output schema, and safety annotations, the description covers purpose, selection criterion, input shape, and the key image-sourcing constraint. Placement/chaining behavior is left entirely to the schema, which is acceptable given its coverage.

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 all 12 parameters including after/position/parentId placement semantics. The inline example lightly reinforces the title/images shape, and the image-source rule adds meaning for src, but this is baseline-plus rather than substantial new parameter insight.

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+resource ("Insert a picture choice question") and adds the discriminating condition "when choices are inherently visual (products, designs, photos)," which separates it from the many sibling insert*Question tools. An agent can pick this over insertRadioQuestion/insertSelectQuestion without opening a 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 a clear when-to-use criterion ("choices are inherently visual") and a concrete example context ("Pick a style"). It stops short of naming the non-visual alternatives or stating when-not to use it, so it's clear context rather than a full routing 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?

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description only restates the 2+ option constraint that the schema already enforces and adds nothing about insertion placement or effects on existing nodes, which is the real behavioral risk for an insert tool.

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 short, front-loaded sentences with no filler; the core purpose, constraint, and selection criterion are all delivered immediately.

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 100% schema coverage, no output schema, and annotations covering safety, the description covers what an agent needs to select the tool. The main omission is any guidance on the positioning parameters (after/parentId/position) that make an insert call succeed, but those are fully documented in the 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 coverage is 100%, so all ten parameters including after/parentId/position are fully documented in the schema; baseline is 3. The description adds no syntax or format meaning beyond the schema, only echoing the minimum-options rule.

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 (Insert) and resource (radio button question) plus the semantics (single-choice selection). However, it never names or contrasts the many sibling question-insertion tools (checkbox, select, picture choice, switch) that also create choice-based questions, so differentiation is left to inference.

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?

"Use when user must pick exactly one" gives a clear positive usage cue and implicitly excludes multi-select tools like editor_insertCheckboxQuestion. It stops short of explicitly naming the alternative or stating when-not conditions.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is covered. The description adds the 2+ option requirement and format ('native string array'), but that largely restates the schema's minItems constraint and adds little about insertion side effects, positioning behavior, or defaults that isn't already in the schema.

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 short sentences, front-loaded with the action, then the selection cue, then the hard requirement and a concrete example. Every sentence earns its place with no 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?

For an insert tool with no output schema and a fully documented 9-parameter schema, the description covers purpose, usage, and a valid example. It stops short of noting structural pitfalls the schema hints at (e.g., 'after' vs 'position' incompatibility), but nothing essential for calling it 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 worked example clarifies the title/options shape, but the description does not add meaning beyond what the schema already documents for the other seven parameters (after, position, parentId, etc.).

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 ('Insert a ranking question') and immediately differentiates the question type from its many siblings by defining the respondent behavior ('order items by preference, drag to rank'). An agent can distinguish this from insertRatingQuestion or insertRadioQuestion without opening either 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 clause 'Use when the respondent must order items by preference (drag to rank)' gives a clear selection context against sibling question types. It does not explicitly name alternatives or when-not conditions, but the semantic cue is strong enough for correct 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the mutation/safety profile is covered. The description adds no behavioral context beyond that - nothing about placement behavior, chaining, or what happens to sibling nodes - so it does little to enrich the annotation set.

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, front-loaded sentences with zero filler. The core action leads and the usage hint follows immediately.

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 8 parameters and no output schema, the description is thin relative to the tool's complexity - especially the non-trivial insertion-positioning options the schema documents. The annotations and full schema coverage carry most of the load, but a sentence on placement or required context would round it out.

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 all eight parameters are already documented (including placement semantics for after/parentId/position and the isHidden/show-rule note). The description adds no parameter detail, so the 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?

States a specific verb and resource ('Insert a star rating question'), clearly distinguishing it from sibling question types like insertLinearScaleQuestion or insertNumberQuestion. It does not explicitly name those siblings, but the resource specificity is enough for an agent to disambiguate.

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?

'Use for satisfaction scores, reviews' gives a use-case cue that implies when this question type is appropriate. However, it names no alternatives and gives no when-not guidance, leaving the agent to infer the boundary against rating-style siblings such as linear scale or number.

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 declare this is a non-readonly, non-destructive, closed-world write. The description goes well beyond that: the auto-deletion rule for empty groups, the @-mention behavior for group and member ids in body/email/PDF, and the returned `members` array shape all disclose behavior an agent could not infer from 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?

It is a dense single paragraph, but it is front-loaded with the definition and every sentence carries distinct, non-redundant information. It is longer than ideal, yet the length is justified by the tool's complexity rather than 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?

No output schema exists, and the description compensates by describing the `members` return payload in detail. Combined with creation constraints, id-reuse guidance, and routing to sibling insert tools, an agent has everything needed to call this 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%, so baseline is 3, but the description adds cross-parameter meaning — the parentId linkage for post-creation member inserts, which types require options, and the minimum-one-field invariant. It does not explain `after`/`$prev` chaining (that lives in the schema) but otherwise enriches semantics.

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

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

States a specific verb and resource (insert a repeating group) and defines the concept inline with a concrete example ('Who is coming?' repeated per guest). It also implicitly separates itself from the single-question siblings by noting those are used to add members AFTER creation.

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 usage conditions: provide name and 1+ fields (a group with no fields is auto-deleted), choice types need options, and other/complex member types must be added later via editor_insert*Question with parentId = group id. It names the alternative tool family and the exact circumstance that selects it.

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

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

Annotations mark this as a non-destructive, non-open-world write, so safety is covered; the description adds genuinely new behavioral context by disclosing the return shape ('columnIds left to right') and the intended chaining mechanism, which matters because there is no output schema. It stops short of saying what happens to existing siblings or the form layout on insert.

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

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

Two sentences, zero waste, with the core purpose front-loaded and the follow-up workflow second. Nothing is repeated from the schema or annotations.

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 write tool with no output schema, the description covers what is created and what is returned plus how to consume it, which is close to complete. It could add a note on ordering pitfalls or whether the row must be inserted into a specific parent, but the gaps are minor.

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, but the description goes beyond it by tying the returned columnIds to the parentId and position parameters, explaining the relationship between inputs and outputs rather than merely naming fields.

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 ('Insert a row layout element with 1-6 columns') and clarifies the intent ('side-by-side layout'), which cleanly separates it from siblings like editor_insertTable or editor_insertList. An agent knows what this creates 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?

It describes the follow-up pattern (use a returned columnId as parentId with position 'last' to fill the row), which implies a workflow, but never states when to use this tool versus alternatives such as editor_insertTable or editor_insertRepeatingGroup, nor any prerequisites. Usage is implied rather than guided.

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=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavior beyond annotations: the question is backed by Cal.com and requires the creator to connect Cal.com and select an event type afterward, signaling external setup dependency. It does not detail side effects or permissions beyond that, so it is strong but not exhaustive.

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 the core action and immediately followed by usage guidance and the Cal.com dependency. Every sentence earns its place with no filler or repetition.

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

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

For an insert-question tool with full schema coverage and annotations covering safety, the description is nearly complete: purpose, sibling differentiation, and external setup are all present. The only minor gap is that it does not mention what happens if Cal.com is not connected or how the inserted question behaves before setup, but those are secondary for an agent selecting the tool.

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

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

Schema description coverage is 100%, so the schema fully documents all 8 parameters, including insertion mechanics like after, parentId, and position. The description adds no parameter-level meaning beyond what the schema already provides, 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 description states a specific verb (Insert) and resource (Schedule appointment question) and scopes it to Cal.com-backed bookings or appointments. It explicitly distinguishes this from separate date and time questions, which are sibling tools (editor_insertDateQuestion, editor_insertTimeQuestion), so an agent can identify the correct tool 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?

It gives explicit when-to-use guidance ('Use for bookings or appointments') and a clear when-not rule ('do not substitute separate date and time questions'). It also notes the post-insert requirement that the creator connects Cal.com and selects an event type afterward, which routes the agent away from this tool if no Cal.com setup is intended.

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 this is a non-destructive, closed-world write (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the safety profile is covered by structured data. The description adds the option-count precondition, but says nothing about permissions needed, what happens to the form on failure, or that an element/node id is produced. Adequate, not rich.

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

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

Two sentences, no filler, front-loaded with the tool's identity before the routing hint. Every clause earns its place.

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

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

For a 10-parameter insert tool with a fully documented schema and annotations that already cover the write/safety profile, the description supplies the one piece of context the schema cannot: which sibling to pick when multiple answers are needed. No output schema exists, so return values need not be explained, though noting the created element's id would have been a nice addition.

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 every parameter (after, parentId, position, isHidden, required, placeholder, randomizeOptions) is already documented in the schema with usage hints such as '$prev to chain' and 'Not combinable with after'. The description's 'Requires 2+ options' merely restates the schema's minItems: 2. Baseline 3 is correct when the schema carries the 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 gives a specific verb ('Insert'), the exact resource ('dropdown select question'), and the semantic scope ('one answer from a list') that separates it from the multi-answer siblings in the editor_insert*Question family. An agent can immediately tell it apart from editor_insertCheckboxQuestion. The only unstated cousin is editor_insertRadioQuestion, which shares the single-answer semantics, but the stated purpose is unambiguous.

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

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

It states an explicit routing rule: 'For several answers use editor_insertCheckboxQuestion,' and gives a precondition ('Requires 2+ options'). It does not address the closer competitor editor_insertRadioQuestion, so the agent must infer select-vs-radio from the name alone. Clear context, but not a full when/when-not matrix.

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 this is a non-readOnly, non-destructive, closed-world insert. The description adds no behavioral context beyond that — no note about default placement, no auth or permission requirements, and no indication of what the mutation returns or how insertion ordering behaves. For a write tool it does not pull its weight.

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

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

A single efficient sentence with the key noun phrase front-loaded and no filler. It is well-formed, though at one clause it offers no structure for scannability.

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 seven parameters, a mutation-style operation with no output schema, and a dense sibling set, the description is minimal but the rich schema carries most of the load. It is adequate to invoke correctly, but an agent gets no help on selection or on insertion-order semantics that the schema only partially hints at.

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 all seven parameters (including the non-obvious `after`, `position`, and `isHidden`) are documented in the schema itself. The description contributes no additional parameter meaning, so the baseline 3 applies.

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

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

The description names a specific verb (Insert) and a specific resource (signature pad question for handwritten signatures), which clearly distinguishes it from the other ~30 editor_insert*Question siblings. It stops short of explicitly contrasting with alternatives like editor_insertTextQuestion, but the resource is unambiguous.

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

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

There is no guidance on when to use this tool versus other question types, nor any mention of prerequisites (form must exist, region must be editable) or when-not-to-use. The agent must infer that this is chosen whenever a signature field is wanted.

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=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing behavioral beyond that: no mention of defaults (e.g., required defaults to true), insertion/positioning side effects, or return behavior.

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

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

A single clean sentence with the key semantic detail (yes/no or on/off) front-loaded. It is tight, though 'for yes/no or on/off responses' is somewhat redundant with the name 'Switch'.

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 seven parameters, no output schema, and annotations covering only safety, the description is minimally adequate. It omits insertion-positioning behavior and defaults that an agent must recover from the schema, but nothing critical is entirely 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 all seven parameters including after/$prev chaining, position, parentId, and isHidden are fully documented in the schema. The description contributes no additional parameter meaning, which is the baseline 3 case.

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 ('Insert a toggle switch question') and clarifies the answer type as yes/no or on/off, which is real substance. It does not explicitly distinguish itself from the many sibling insert*Question tools (radio, checkbox, select), leaving the agent to infer the difference from the name alone.

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

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

No when-to-use or when-not-to-use guidance. Given roughly a dozen sibling question-insertion tools, the description never says when a switch question is preferable to a checkbox or radio question, nor any prerequisites.

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=false, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds the useful distinction that this is static content rather than an interactive question, but says nothing about permissions, reversibility, or insertion side effects. Adequate but not rich given annotations carry the safety burden.

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 tight sentences with the disambiguation front-loaded, followed by a compact example. Every element earns its place; 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 an insert tool with no output schema and annotations covering safety, the description supplies purpose, the sibling alternative, the key type constraint, and a concrete example. Nothing needed 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%, so baseline is 3, but the description adds a concrete gotcha ('rows and cols are numbers, never strings') and a full worked example showing the nested cells layout that the schema only describes abstractly. This materially helps correct invocation.

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 ('Insert a static content table') and immediately disambiguates from the closest sibling by naming editor_insertMatrixQuestion for rating grids. An agent can distinguish this from the many editor_insert* tools 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?

Explicitly gives the when ('static content, text cells') and the when-not ('NOT a question; for rating grids...'), and routes to the alternative by name. Nothing about tool selection is left 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 already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing behavioral beyond content type—no mention of side effects, ordering constraints on the form tree, or what inserting does to existing elements—so it earns little credit above the annotations.

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

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

Two short sentences, front-loaded, with zero filler. Every clause earns its place by naming the field type and typical uses.

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 14-param insertion tool with full schema coverage and no output schema, the schema carries the mechanical burden, so the description needn't explain parameters. Its main gap is distinguishing this tool from the many sibling question-insertion tools, which the description only partially does by content type.

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 14 params are thoroughly documented, including subtle placement semantics (after, position, parentId) and defaults. The description contributes no parameter-level meaning, 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+resource ('Insert a text question') and scopes the response type ('short or long text responses'). It partially differentiates from sibling question types by content type, but never names the alternatives (e.g. editor_insertParagraph, editor_insertSelectQuestion) that an agent must choose between.

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?

'Use for names, comments, descriptions' gives implied usage context for free-text fields. However, it offers no when-not-to-use guidance and no explicit routing among the ~35 sibling insert tools, leaving the agent to infer that this is for free text rather than select, paragraph, or other field types.

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=false, destructiveHint=false and openWorldHint=false, so the safety profile is known. The description adds nothing beyond that: it doesn't say the insert mutates the form structure, where the new node lands, or what a failure looks like. All placement behavior lives only in the schema.

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

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

A single short, front-loaded sentence with no filler. It is efficient, though the brevity borders on under-specification rather than true conciseness.

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 nine parameters, a large sibling set, and no output schema, the description is thin — it never mentions placement (after/parentId/position) or that this is a structural mutation of the form. The rich parameter schema and the annotations cover most of the gap, keeping it at minimum-viable rather than inadequate.

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%, including useful notes on 'after', 'position' and 'isHidden', so the schema does the heavy lifting. The description contributes no parameter meaning of its own, which is exactly the baseline-3 case for high coverage.

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: 'Insert a time picker question', which is enough to distinguish it from the many sibling insert*Question tools (e.g. editor_insertDateQuestion). It stops short of naming an explicit contrast, but the resource noun is unambiguous.

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

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

There is no when-to-use guidance, no prerequisites (e.g. that the form must exist / be editable), and no mention of alternatives such as editor_insertDateQuestion. The agent gets no help choosing this over its 30+ sibling insert tools beyond the word 'time'.

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=false, destructiveHint=false, and openWorldHint=false, so the mutation-but-not-destructive profile is covered. The description adds the field-type compatibility (hidden, calculated, question inputs) but nothing about what insertion changes, offset edge cases, or failure behavior.

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 with the core action front-loaded and the usage examples last. Every sentence contributes; 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 5-required-param mutation tool with a fully documented schema and no output schema, the description covers purpose, field compatibility, and usage sites well. It is only missing return/error behavior, which is minor given the schema depth.

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%, including the tricky offset semantics and examples for nodeId/fieldId, so the schema carries the load. The description repeats the field-type constraint (hidden/calculated/question) but adds no syntax or format detail 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 states a specific verb (insert) and resource (variable reference inline), and clarifies the intent is answer piping. It implicitly separates itself from siblings like editor_insertHiddenField or editor_insertCalculatedField by saying it references existing fields rather than creating them, though it never names those siblings explicitly.

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?

"Use in paragraphs and headers to show dynamic values like recipient names, scores, totals, or piped answers" gives clear contextual guidance for when to reach for this tool. There is no explicit when-not or named alternative, but the use case is unambiguous.

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=false and destructiveHint=false, so the bar is lower, yet the description adds real behavior: rule replacement semantics (one rule per element), ID validation on referenced questions/pages/fields, and the prerequisite of reading the document first. The non-obvious side-effect requirement (also set isHidden:true on shown questions) is especially valuable. It slightly undersells the replace-existing-rule data loss relative to destructiveHint=false, keeping it from a 5.

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

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

Five short sentences, front-loaded with the core action and replacement semantics, then prerequisites, then the pitfalls, then a pointer to deeper docs. Every sentence carries distinct actionable information with no 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?

For a complex nested-schema mutation tool with no output schema, the description covers action, alternatives, removal path, ID validation, prerequisites, and a tricky default-visibility side effect. No further information is 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 nested rule/condition/action structures are documented exhaustively in the schema itself, including 'Single replacement rule. Insert another logic block for each additional rule.' The description's mention of a 'single conditional rule' and nodeId therefore largely restates schema content, so baseline 3 is right.

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 precise verb+resource: 'Overwrite the single conditional rule on a logic element identified by nodeId.' This immediately distinguishes it from sibling editor_insertLogic, which the description implicitly covers by telling the agent to insert separate logic elements for additional rules.

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?

Explicit when-to-use routing: use this to overwrite, insert separate elements for additional rules, delete the element to remove a rule, and read editor_getDocument first for valid IDs. It even points at load_skill("logic-rules") for deeper guidance, 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and the description's 'Read-only' merely repeats that. The one genuinely additive statement is that it uses the same engine as the published form runtime, which signals high-fidelity simulation — useful, but nothing about error behavior or result shape is disclosed.

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 short sentences with the core action front-loaded, followed by the safety trait and the fidelity guarantee. Zero 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 no output schema, the description does name the three result categories the agent gets back (visibility/required/calculated), which is the key gap-filler. It stops short of describing how results map to fields or how missing/invalid answers are handled.

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 50%: formId is undocumented but self-evident, while answers carries a thorough schema description covering field-ID keys, per-type values, and the payment special case. The description adds only the loose phrase 'sample answers' on top of that, so it neither compensates for nor extends the schema meaningfully.

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: simulate logic rules and return visibility/required/calculated results. An agent can distinguish it from editor_setLogic (which writes logic) and editor_insertLogic (which creates logic elements) by the simulation framing, though no sibling is named explicitly.

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 phrase 'against sample answers' and 'Read-only' imply this is a dry-run tool for verifying logic before publishing, but no when-to-use or when-not-to-use condition is stated, and no alternative (e.g. editor_setLogic) is referenced. Usage must be inferred.

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

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

With readOnlyHint=false already signalling mutation, the description still adds meaningful behavior: properties is partial (send only what changes), null clears a default/validation rule, content is a whole-element replace not substring, and validation keys are per-input-type. It doesn't cover perm/auth or error behavior, but the added mutation semantics are substantial.

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 the core action, then dense per-field guidance with no filler. It is long, but virtually every clause carries node-type constraints or examples that earn their place; only minor density cost keeps it from 5.

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 5-param nested mutation tool with no output schema, the description covers input semantics, prerequisites, and the sibling hand-off for logic. It leaves the return shape unstated, but with no output schema and annotation coverage of the safety profile, the gap is minor.

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 only 60%, and the description compensates richly: it maps each property to its valid node type (maxStars→rating-input, min/max/minLabel/maxLabel→linear-scale-input, multiple→picture choice only), shows validation examples like {maxLength:80} and {minDate:"2026-01-01"}, and gives concrete moveTo payloads.

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+resource (edit one element by nodeId) and enumerates the three mutating operations it performs (text, props, reposition) in one call. It clearly distinguishes itself from the editor_insert* and editor_deleteElement siblings by being the edit-in-place 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?

Gives a hard prerequisite (call editor_getDocument first, copy nodeId, never guess/reuse an old ID) and routes conditional-logic work to editor_setLogic. It also states content is invalid on input/option shells and points to properties.label instead. It lacks broader when-to-use-vs-siblings guidance (e.g. vs editor_formatText), so not 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?

Annotations already establish the read-only safety profile, and the description adds real behavioral context beyond them: it reads the currently published version only, must be re-read after publish, returns { items, next }, and each item's key-vs-label rule for prefill is stated explicitly. This goes well past what structured fields convey.

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?

Dense but front-loaded: purpose first, then the routing instruction, then the return shape. Every clause carries information (usage line, options key-not-label, matrix rows/columns) 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?

With no output schema, the description fully compensates by describing the return envelope and item shape, including the edge case of option questions and matrices. An agent has everything needed to call and consume it.

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 a single parameter (formId) with 100% schema description coverage that already tells the agent where to get the id. The description's detail about prefill/context and option keys concerns the returned fields rather than the input parameter, so it adds little meaning to the parameter itself; 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 ('List the field keys a request can address on a published form') plus the distinguishing scope (addressable keys, value types, option keys, prefill vs context). It is clearly separable from siblings like form_get or request_create.

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-to-use ('Call this before request_create instead of guessing keys from question titles') and a concrete re-use trigger ('re-read it after form_publish'). No alternatives are left 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 already declare readOnlyHint/openWorldHint/destructiveHint, yet the description adds substantial behavior beyond them: the Pro-feature gate and its UPGRADE_REQUIRED terminal behavior (including history recorded while Pro), the deduplication semantics that make breakdown counts unique visitors while totalEvents is the raw pre-dedup count, and the specific response shape when from/to are omitted (period: { from: null, to: null }).

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 most important facts are front-loaded: what it returns, then read-only, then prerequisites. It is dense but each sentence carries distinct information (return shape, dedup rule, default period, gating). The only minor waste is 'Read-only', which the readOnlyHint annotation already conveys.

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 7-parameter read tool with no output schema, the description compensates fully: it documents the return object keys, the meaning of totalEvents vs deduplicated breakdown counts, the all-time default period, and the error path for non-Pro workspaces. An agent has everything needed to call and interpret it.

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, but the description goes further by stating that rate metrics are 0–100 numbers vs integer counts, that breakdown counts are per-unique-visitor, that includeEvents returns sanitized events without visitor IDs, and by restating the from<=to constraint. That adds real interpretive value over the property 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 specific verb+resource ('Get form analytics') and enumerates exactly what is returned: views, submissions, completion rate, bounce rate, and device/browser/country/traffic-source breakdowns. This clearly distinguishes it from siblings like form_list, form_get, and formSubmission_list, which serve different purposes.

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

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

It gives an explicit prerequisite ('Use form_list to find formId first') and a concrete usage recipe ('for completion on one device, filter by device and read completionRate'), plus the Pro-plan condition that yields UPGRADE_REQUIRED. It stops short of stating when *not* to use it, but no competing analytics sibling exists, so the routing guidance is largely complete.

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 it is a write (readOnlyHint=false) but non-destructive and not open-world. Beyond that, the description discloses the return payload (the form plus a previewUrl for live edits) and the required downstream tool chain, which is meaningful since no output schema exists. It omits permission/auth requirements and duplicate-name behavior.

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 purpose in the first sentence, then adds return info and the follow-on workflow. Three sentences, each with a distinct job, though the enumerated insert-tool examples are mildly verbose.

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

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

With no output schema, describing the return value and the editing workflow is a real contribution, but with 0% parameter coverage the description leaves folderId and name semantics undocumented, and says nothing about failure modes or prerequisites. Adequate but with clear gaps for a 3-parameter creation tool.

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

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

Schema description coverage is 0% for all three parameters. The description only indirectly implies workspace scope ('in a workspace') and never mentions name constraints or the optional folderId at all, so the agent gets no semantics for folder targeting or naming rules.

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 ('Create a new form in a workspace'), which cleanly separates it from form_update, form_get, and the unrelated document_create sibling. An agent can identify the operation 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 explicit workflow guidance: after creation call editor_getDocument, then chain editor_insert* tools with after: "$prev". It does not compare against alternatives like document_create or explain when a form is preferable to a document, so it is slightly short of full when/why-to-use guidance.

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

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

The description adds substantial behavioral context beyond the destructiveHint annotation: it specifies soft deletion, revocation of active share links, that restoring does not re-enable revoked links, and that new links must be minted with formShareLink_create. This is rich operational disclosure for a destructive tool.

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 front-loaded: the primary action and soft-delete nature appear first, followed by important side effects and the restore path. Every clause carries useful information.

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 absence of an output schema and the simple one-parameter input, the description covers the critical behavioral outcomes an agent needs: soft deletion, link revocation irreversibility, and restore/link alternatives. It is complete enough for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate for the unexplained formId parameter, but it does not describe the expected format, source, or constraints of formId. It only implies that a form is targeted, which the parameter name already conveys.

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 and resource: 'Move a form to trash (soft delete).' It clearly distinguishes this soft-delete operation from permanent deletion and from sibling tools like form_restore and formShareLink_create.

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

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

The description implies when to use this tool by stating the action and consequences, and it names related alternatives: form_restore for restoration and formShareLink_create for new links. However, it lacks an explicit when-not/alternative comparison against tools such as form_unpublish.

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, openWorldHint=false, and destructiveHint=false. The description adds useful return behavior: a previewUrl for live edits and support for both draft and published forms, though auth/error behavior is not covered.

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

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

Two sentences, front-loaded with purpose and then a key return detail. Every sentence earns its place with no wasted text.

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

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

For a simple one-parameter read tool with rich safety annotations, the description is adequate but incomplete: it omits parameter source and any detail about returned fields beyond previewUrl. The absence of an output schema means more return context would help.

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 0% and the sole parameter formId has no description. The description only says 'by ID,' which does not explain what identifier is expected or where to obtain it, so it fails to compensate for the schema gap.

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 (Get), resource (form details), and scoping (by ID). However, 'details' is broad and does not explicitly distinguish it from sibling retrieval tools like formSettings_get or formTheme_get.

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

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

No when-to-use guidance or alternatives are provided. The note that it works for draft and published forms is contextual, but the agent must infer that this retrieves general form details rather than settings, themes, analytics, or lists.

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 a safe read operation (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description earns real credit by disclosing a non-obvious constraint: query results are capped at `limit` with a truthful hasMore but cannot be paginated further, while cursor pagination only works on the unfiltered path. Auth needs and rate limits remain unstated.

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 core purpose and packs three distinct behavioral clauses into a few sentences, all of which carry information. The trailing sentence about forms created via request_create carrying origin 'inline' is tangential and mildly confusing in context.

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

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

With no output schema, the description carries return-value burden; it covers the critical pagination contract (hasMore, nextCursor, cap on filtered search) but never describes what a returned form object contains or result ordering. Complete on the behavioral pitfalls, incomplete on payload shape.

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 80%, so the baseline is 3. The description largely restates folderId and query semantics, but adds genuine value by describing the interaction between `query` and `cursor` (mutually exclusive pagination paths) that the schema does not capture.

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 ('List forms') scoped to a workspace, and immediately characterizes the two optional filter modes. Against a large sibling set that includes form_get and fields_list, an agent can tell this is the collection-listing operation 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 concrete operational guidance: folderId=null means root-only, omit for all, and explains when to use `query` versus `cursor`. It does not explicitly name sibling alternatives (e.g., form_get for a single form), but the routing conditions for its own two modes are 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 declare the generic write profile (readOnly=false, destructive=false, openWorld=false). The description goes well beyond them by disclosing idempotency semantics, the warning behavior for forms with content blocks but no questions, and the failure mode with a concrete remedy. These are behavior traits 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?

Four short sentences, front-loaded with purpose, each carrying distinct information (idempotency, warning case, failure case, next step). No filler and nothing repeated from the schema or annotations.

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 mutation with no output schema, the description covers purpose, idempotency, edge cases, failure remediation, and the logical next call. Nothing an agent needs to invoke 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?

Only one parameter (formId) with 0% schema description coverage, and the description never elaborates on it. However, formId is self-evident from its name and required status, so the gap is minor rather than disqualifying; a 3 reflects adequate-but-thin coverage.

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 ('Publish a form's current content') and clarifies the resulting state ('make it live'), which cleanly separates it from form_unpublish and form_update among the siblings. An agent can tell what it does 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?

Explicitly gives the precondition for failure ('Forms with no editor content cannot be published') and the alternative remediation path ('call editor_insertHeader or editor_insertTextQuestion first'), plus the natural follow-up tool (formShareLink_create). This is exactly the when/when-not/alternatives guidance the dimension asks for.

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 a non-read-only, non-destructive, closed-world mutation, and the description goes beyond them by explaining exactly where the restored resource lands. It omits failure behavior (e.g. what happens if the form is not in trash) and any permission requirements, so it is strong but not exhaustive.

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

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

Two sentences, zero filler, with the core action front-loaded and the parameter details following in the order an agent needs them. Every clause carries information.

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 two-parameter mutation with no output schema and no nested objects, the description supplies everything required to invoke it correctly. Only the absence of error/prerequisite behavior keeps it from being fully complete.

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

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

Schema description coverage is 0%, so the burden falls on the description, and it delivers: the omitted-vs-null-vs-string distinction for folderId is a tri-state semantic that the schema's type: [string, null] cannot express. formId is left unexplained, though its meaning is self-evident from the tool name.

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 ('Restore a form') and adds scope ('from trash'), which lets an agent distinguish it from form_delete and form_update without opening a schema. No ambiguity about what the tool achieves.

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 destination-resolution sentence gives operational context (omit vs null vs string), but there is no explicit when-to-use or when-not guidance and no named alternative such as the sibling form_delete that presumably puts a form in the trash. Usage is implied rather than stated.

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

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

Annotations already establish the safe-read profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's extra value is the return payload: it names the settings groups plus isDefault, availableEmailDomains, defaultFromAddress, and payment. No output schema exists, so this disclosure is genuinely additive; it stops short of describing auth needs or domain-verification semantics.

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

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

Two sentences, no filler: purpose first, return shape second. Every clause (email config, domains, Stripe status, response keys) earns its place for a tool with no output 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 no output schema, the description correctly compensates by enumerating the response object's top-level keys, and the single required param is fully documented in the schema. Slightly incomplete in that it does not explain what isDefault distinguishes or how availableEmailDomains differs from the active domain.

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?

Single formId parameter with 100% schema description coverage ('Form ID to get settings for'), so the schema carries the semantics. The description adds nothing about the identifier's format or source, which is the expected baseline-3 outcome here.

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

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

Specific verb+resource ('Get form settings') with an enumeration of exactly what the settings contain: notification email config, respondent emails, email domains, Stripe payment status. This implicitly separates it from form_get (form metadata) and formSettings_update, though it never names those siblings to make the split explicit.

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

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

No when-to-use guidance, no prerequisites, and no pointer to formSettings_update as the mutation counterpart. The agent must infer from the name that this is the read side of the settings pair.

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