formbase (formbase.so)

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

Annotations only cover the safety profile (write, non-destructive, closed-world). The description goes well beyond them: it discloses the return shape, states bytes never pass through the tool, documents the one-hour uploadUrl expiry, and describes downstream verification via request_create.

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

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

Single tight paragraph, front-loaded with the purpose, then the return contract, then the required follow-up steps. No sentence is filler; even the load_skill pointer adds routing value.

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

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

There is no output schema, but the description inlines the returned fields ({ id, uploadUrl, expiresAt, name, contentType, size }) and the complete two-step upload handoff, so an agent has everything needed to invoke and chain the tool correctly.

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

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

Schema coverage is 100% with per-field descriptions and constraints (max size, enum content types, sha256 pattern), so the schema already carries the parameter meaning. The description reinforces the workflow linkage (declared Content-Type, id reused as documentId) but adds no unique per-parameter detail, matching the baseline-3 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?

Starts with a specific verb+resource ('Reserve an upload for one document... through the form's Documents block'), clearly identifying the object and the mechanism (upload reservation, not the file transfer itself). It distinguishes itself from the request-side siblings by naming the follow-on tool request_create and the Documents block context.

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

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

Gives an explicit end-to-end workflow: call this to reserve, PUT bytes to uploadUrl within one hour, then pass { documentId: id } into request_create's documents. It also notes 'one upload serves any number of requests' and points to load_skill("requests"), so the agent knows the surrounding process as well as the trigger condition.

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?

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 readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds no behavioral context beyond the schema — 'Requires 1+ options' merely restates the existing minItems:1 constraint, and nothing is said about insertion ordering, mutation side effects, or interaction with 'after'/'position'.

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, zero waste, with the core purpose front-loaded followed immediately by the key gating rule. Nothing 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 an 8-parameter insertion tool with positional complexity (after vs position, parentId, default required=true), the description is thin, but the fully-covered schema carries that burden and there is no output schema to explain. It is adequate but leaves the ordering/mutation semantics 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%, so all 8 parameters are already documented in the schema (including the tricky after-vs-position distinction and $prev chaining). The description only echoes the options requirement, adding no meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource (insert a checkbox question) and its selection semantics (multi-choice, user can pick multiple). This implicitly distinguishes it from the many sibling question-insertion tools (radio, select, picture-choice), though it never names the closest alternative 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 when user can pick multiple' gives a clear selection criterion that routes the agent away from single-select siblings. It stops short of an explicit exclusion (e.g. 'use insertRadioQuestion when only one answer is allowed'), so it's clear context rather than a full when/when-not statement.

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 as a non-destructive, non-read-only, closed-world mutation, so safety is covered. The description adds no behavioral context beyond that — nothing about insertion side effects, required permissions, idempotency, or what happens when placement params conflict.

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 no filler. The second sentence is thin but still orients the agent toward the required contactType decision, so little is wasted.

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 nested objects and no output schema, the description is minimal but the schema compensates fully with rich per-parameter docs. Nothing critical is missing, but the description does not enrich the picture beyond purpose.

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 itself already documents all 11 parameters, including the nuanced after/position/parentId placement rules and defaultValue vs defaultValueFieldRef exclusion. The description adds only the contactType choice hint, so 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 (insert) and resource (contact question) plus its scope (email, phone, or URL), which separates it from the many other editor_insert*Question siblings. It is clear what the tool creates, though it does not explicitly name which sibling to use instead.

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 only guidance is 'Choose contactType based on what information you need,' which is really a parameter hint rather than a when-to-use statement. Nothing tells the agent when to pick this over editor_insertTextQuestion or other question-type tools, and no prerequisites or ordering constraints are 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 declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the mutation/safety profile is covered. The description adds nothing beyond that: no note on whether the insert is reversible, what happens to ordering, or that required defaults to true — all of which live 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 front-loaded sentence with no waste. It is appropriately sized, though it is arguably too terse given the crowded insert-tool family it belongs to.

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

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

The tool has no output schema, so return values need not be explained, and the schema covers all parameters. What is missing is context about how this question type differs from the many other question-insertion siblings, which is the key disambiguation an agent needs in this toolset.

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 7 parameters (including the subtle after/position/parentId placement semantics) are documented in the schema itself. The description contributes no additional parameter meaning, so baseline 3 applies.

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

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

The description gives a clear verb+resource ('Insert a date picker question'), so an agent can identify the operation. However, it offers no differentiation against close siblings like editor_insertTimeQuestion or editor_insertScheduleAppointmentQuestion, leaving the boundary between date/time/schedule ambiguous.

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 explicit when-to-use guidance, no prerequisites (e.g. needing an existing formId), and no routing to alternative insert tools. The usage context is only implied by the tool name.

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 structurally. The description adds a genuinely non-obvious behavioral fact beyond the annotations: this element is what actually drives a request's outcome, unlike a plain radio. It does not mention anything about placement conflicts 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?

Two short sentences, zero filler, with the core purpose front-loaded and the sibling disambiguation as the second beat. Nothing could be removed without losing signal.

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 insertion tool with nested object params, no output schema, and rich schema-level documentation, the description covers the essential conceptual gap (why this question type exists vs. a radio) while the schema carries parameter detail. It is nearly complete; only explicit placement/prerequisite guidance 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 all 8 parameters (including after, position, parentId, labels) are already documented in the schema, including the useful '$prev' chaining note and the 'usually wrong' append warning. The description adds no parameter-level meaning of its own, 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 ('Insert') and a precise resource ('the decision question') and immediately defines the resource's semantics (approve / decline / request changes) and its effect ('sets a request's outcome'). It also explicitly distinguishes itself from the nearest sibling (a plain radio) which is exactly the ambiguity an agent would face in this large insert_* family.

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 line 'A plain radio never sets an outcome' functions as an implicit when-to-use rule, steering the agent away from editor_insertRadioQuestion when an outcome-setting control is needed. It is clear context but stops short of an explicit 'use this instead of X when Y' statement or any prerequisite about form state.

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 disclose the write-but-non-destructive, non-open-world profile, so safety is partly covered. The description adds nothing beyond restating the purpose and naming configurable options that the schema already documents; it says nothing about insertion ordering effects, required defaults, or what happens on success.

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 no filler. The second sentence is largely redundant with schema properties, which is the only minor waste.

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

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

For a 10-parameter mutation tool with no output schema and rich sibling competition, the description covers the 'what' but not the 'how/when' — insertion ordering, chaining rules, and required-field defaults all live only in the schema. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so the schema fully documents all 10 parameters including the non-obvious 'after'/$prev chaining and 'position' semantics. The description's mention of accepted file types and size limits merely echoes schema fields, adding no extra meaning. 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 file upload question') that is immediately distinguishable from other insert tools by name. However, it offers no differentiation from the many sibling question-insertion tools (insertCheckboxQuestion, insertTextQuestion, etc.) beyond the resource noun itself.

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

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

No guidance on when to use this tool versus other question types, no prerequisites (e.g., needing a formId), and no mention of the positioning/chaining behavior implied by the 'after' and 'position' params. The agent must infer everything from the schema.

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 write. The description adds genuinely new behavioral context beyond that: the header level is immutable after insert and editor_updateElement can only change isHidden, required, and titleIsHidden. That immutability constraint is exactly the kind of trait annotations cannot express.

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 no filler. Purpose comes first, then the level scale, then the immutability caveat — a well front-loaded ordering that an agent can act on 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?

For a 7-parameter write tool with no output schema, the description covers the purpose, the level semantics, and the key post-insert constraint. It says nothing about what is returned (e.g., the new node ID) which matters for chaining with $prev/after, but the schema's 'Use $prev to chain' note largely compensates.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by clarifying that level 1 = largest and that 1-4 map to sizes. It also contextualizes which props updateElement supports later, tying back to isHidden/required/titleIsHidden semantics.

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

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

The description states a specific verb and resource ('Insert a heading element'), which cleanly separates it from siblings like editor_insertParagraph or editor_insertList. It is clear about what is produced, though it never explicitly contrasts itself with the closest sibling (paragraph/rich-text insertion), 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?

Usage is implied rather than stated: a reader infers this is for headings of level 1-4 versus body text elsewhere. There is no explicit when-to-use/when-not guidance or named alternative for the 'insert text block' decision, but it does give useful context on the level scale.

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 declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, covering the safety profile. The description adds no behavioral context beyond that (no mention of mutation effects, placement side effects, or auth needs), so it does not exceed the annotated baseline.

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 variant guidance and a compact example. Little waste; the "native string array" note is slightly redundant with the schema type declaration.

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 description coverage and no output schema, the description covers what the schema does not (variant meaning, example). Placement semantics (`after`/`position`/`parentId`) live in the schema and are not echoed, which is acceptable given full 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 coverage is 100%, so the baseline is 3, but the description meaningfully expands the terse schema enum for `variant` ("ordered" = numbered, "unordered" = bullets) and clarifies `items` is a native string array with a concrete example.

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

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

States a specific verb+resource ("Insert a list element") and clarifies the two variants. It does not explicitly distinguish itself from the many sibling insert tools (insertParagraph, insertRadioQuestion, etc.), so an agent must infer the list-vs-other-element 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?

The description explains how to drive the `variant` enum but gives no explicit when-to-use guidance, prerequisites, or alternatives among the large family of editor_insert* tools. Usage is only implied by the word "list".

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 write/readOnly/destructive profile; the description adds non-obvious behavior — that a 'show' action leaves the target visible in the editor baseline unless isHidden:true is also set, and that chaining/multiple rules require separate inserts. That is meaningful operational context beyond the structured fields.

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

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

Front-loaded with the core action, then constraint, then the side-effect gotcha, then a pointer. Every sentence carries an instruction or warning; the wording is dense but not 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 deeply nested, high-complexity insert tool with no output schema, the description covers the critical gotchas (one rule per element, isHidden side-effect) and defers detail to load_skill. It omits any mention of the placement/`after` chaining behavior, which the agent must get from 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 the schema documents parameters in depth; baseline would be 3. The description goes beyond it by tying the 'show' action semantics to a required isHidden mutation on the target, which the schema alone does not connect.

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?

Opens with a specific verb+resource ('Insert one logic element containing exactly one conditional rule'), and the 'exactly one rule' scope is a real distinguishing constraint. It stops short of naming or contrasting the adjacent siblings editor_setLogic / editor_testLogic, so an agent still infers which of the logic tools to pick.

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 usage rules: one rule per element, insert separate elements for additional rules, and the show-action pairing with isHidden. It also routes to load_skill("logic-rules") for depth. No explicit when-not or direct contrast with setLogic, so not a full 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 declare the safety profile (readOnly=false, destructive=false, openWorld=false), so the agent knows this is a non-destructive create. The description adds a real behavioral gotcha beyond annotations: rows/columns must be native string arrays and never a JSON string. It does not mention permissions or insertion side effects, so not 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 tight sentences, front-loaded with purpose, then usage, then the param constraint and a compact example. Every sentence earns its place and the example is illustrative rather than 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 9-param creation tool with no output schema and safety covered by annotations, the description gives purpose, usage, and a concrete example. It omits the ordering/chaining semantics (after, position, parentId), but those are documented in the schema, so it is largely complete.

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

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

Schema coverage is 100%, so baseline is 3. The description exceeds it by illustrating the shape of the key params (title/rows/columns) and flagging the native-array-vs-JSON-string pitfall. It leaves the ordering params (after, position, parentId) 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 and resource ('Insert a matrix/grid question') and clarifies the matrix/grid concept that distinguishes it from the ~25 sibling editor_insertXQuestion tools. An agent can identify 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 clear usage context ('Use when rating multiple items on the same scale'), which separates it from a plain rating question. However, it names no explicit alternative or exclusion (e.g., vs editor_insertRatingQuestion or editor_insertLinearScaleQuestion) for the borderline grid-vs-scale case.

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 mutation/safety profile is covered. The description adds nothing beyond the safety hints — no mention of required formId scope, ordering effects, or interaction with logic rules (e.g. isHidden being a show-rule target).

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 sentence is front-loaded and wastes no words. But it is under-specified rather than genuinely concise — there is almost no information to compress, so brevity here is thinness, not efficiency.

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 six parameters and rich insertion-position semantics (after vs position vs parentId), the description is too thin. No output schema exists, and the description does not compensate by explaining placement behavior, chaining, or what a paragraph element represents in the form.

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 (after, formId, content, isHidden, parentId, position) are already documented with useful detail, including the $prev chaining and HTML-entity warning. The description adds no parameter meaning, which is the expected baseline when the schema carries the load.

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 clear verb+resource ('Insert a paragraph element') and adds a hint of purpose ('for descriptive text'). However, among ~35 insert_* siblings it makes no attempt to distinguish itself from near-neighbors like editor_insertHeader or editor_insertList beyond the generic 'descriptive text' phrase.

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

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

No guidance on when to use this versus the many other insert tools, nor when not to. The schema notes that omitting `after` 'appends to end (usually wrong)', but that caveat lives in the schema, not the description, and no alternative routing is offered.

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 cover the safety profile (readOnly=false, destructive=false, openWorld=false), so the bar is lower. The description still adds real behavioral value beyond them: a hard anti-hallucination rule about image URLs and a structural example showing the expected payload shape.

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: purpose, selection criterion, then a compact example plus the critical sourcing caveat. Every sentence earns its place and the selection condition is front-loaded before the example.

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 insertion tool with full schema coverage and no output schema, the description supplies what the structured fields don't: when to pick this question type, the payload example, and the image-sourcing rule. It is adequate, though it could note the after/position chaining intent that the schema only 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 nine parameters (including after/position chaining rules and storageId) are already documented; the baseline of 3 applies. The inline example adds marginal shape clarity for the images array but no syntax detail the schema does not already carry.

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 picture choice question') and immediately scopes it against the large family of sibling question-insertion tools by declaring the condition that selects this one: 'when choices are inherently visual (products, designs, photos).' An agent can distinguish it from editor_insertRadioQuestion or editor_insertImage without opening any schema.

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

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

Gives clear positive selection criteria (visual choices) and an explicit sourcing constraint ('use images the user uploaded or URLs they provided — never invent or guess image URLs'). It does not name alternative siblings or state when *not* to use it, so it falls short of the 5-level explicit routing seen in the calibration example.

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 safety profile (readOnly false, destructive false, closed-world), so the bar is lower. The description restates the 2+ option constraint, which the schema already enforces via minItems, and says nothing about placement behavior, error handling, or what happens to existing elements. It neither contradicts nor enriches the annotations meaningfully.

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 brief sentences, front-loaded with the action and followed by the constraint and selection condition. 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 insert tool with no output schema, the description is adequate on what it inserts but silent on the placement story (after vs. position vs. parentId) that dominates the schema and is easy to misuse. The schema covers it, but the prose does not help the agent navigate the tool's main complexity.

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 eight parameters including the subtle after/position/parentId placement semantics are already documented in the schema. The description adds no parameter detail beyond duplicating the options minimum, so 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 (Insert) plus resource (radio button question) and adds the differentiating semantic: single-choice selection. This cleanly separates it from siblings like editor_insertCheckboxQuestion and editor_insertSelectQuestion without requiring 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?

'Use when user must pick exactly one' gives a clear selection condition and implicitly rules out multi-select siblings. It stops short of naming an explicit alternative to route to, so it is not a full 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 the tool is a non-read-only, non-destructive mutation. The description adds the drag-to-rank interaction and the 'requires 2+ options' constraint, but the option constraint is already enforced by the schema, and no additional behavioral traits such as insert side effects, chaining behavior, or placement defaults are disclosed beyond what structured fields provide.

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

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

The description is front-loaded with the core action, followed by usage context and a compact example. Every sentence earns its place and there is no redundant or filler 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 an insert tool with eight parameters, full schema description coverage, and no output schema, the description provides enough context to select the tool and understand its core requirement. It could be slightly more complete by mentioning placement behavior at a high level, but that detail is fully available 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 description coverage is 100%, so all eight parameters already have documented meanings. The description includes an example using title and options, which is mildly helpful, but it does not add substantial semantic detail beyond the schema's own parameter 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 states a specific verb and resource ('Insert a ranking question') and immediately clarifies the distinguishing use case: ordering items by preference via drag-to-rank. This is enough to separate it from sibling question-insertion tools such as rating, radio, or select 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?

It gives a clear condition for use: 'Use when the respondent must order items by preference.' However, it does not name alternatives or state when not to use this tool, so it falls short of the full when/when-not/alternatives pattern.

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 the write/non-destructive/openWorld profile, so the description carries the rest: the auto-deletion of empty groups, the @-mention behavior for whole-group and member ids, and the exact return payload. This is substantial beyond annotations, though permission/auth context 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?

Dense but fully front-loaded: the definition comes first, then the constraint, then member types, then the sibling routing, then the return shape. Every sentence conveys operational information 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 non-trivial creation tool with no output schema, the description supplies the return structure (members with nodeId/title/inputId/options), the deletion edge case, and downstream id usage, so an agent has everything needed to call and chain 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%, so baseline is 3, but the description adds practical meaning: fields must be ≥1, choice types need options, and the group and member ids are addressable in body/email/PDF. It explains why parameters matter, not just what they are.

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 immediately distinguishes it from siblings by defining the concept with a concrete example. It also names the sibling family (editor_insert*Question) that handles the cases this tool does not, so an agent can disambiguate 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?

Explicit routing: use this for member types text/number/date/etc. at creation, and add other/complex member types AFTER creation via editor_insert*Question with parentId = the group id. The 'must be born with at least one field or it is auto-deleted' rule gives a clear precondition.

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 declare this is a non-read-only, non-destructive, non-open-world write, so the safety profile is already carried. The description adds real workflow context beyond that: the creator must connect Cal.com and select an event type afterward, implying a multi-step dependency. It doesn't address auth, rate limits, or reversibility, but the annotations cover the safety bar.

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 action and the tool's niche, then a routing caution. No repetition of schema content and 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 write tool with full schema coverage and a done-through annotations safety profile, the description supplies the missing piece: what this question type is for, its Cal.com dependency, and the alternative to avoid. Return values aren't needed (no output schema). Minor gap: guidance on the after/position insertion parameters is 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%, so the schema already documents all 8 parameters, including the tricky after/position/parentId insertion semantics. The description adds no parameter-level detail, so baseline 3 applies rather than a higher score.

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

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

States a specific verb (Insert) and a specific resource (Schedule appointment question), and names the backing service (Cal.com). It distinguishes the tool from its many insert_* siblings by describing the exact question type and how it differs from date/time 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?

Provides an explicit when-to-use ('Use for bookings or appointments') and a when-not-to-use with an alternative ('do not substitute separate date and time questions'). It also tells the agent what happens next (creator connects Cal.com). It doesn't cover insertion-positioning tradeoffs (after vs position) that the schema leaves 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 readOnly=false, destructive=false, openWorld=false, covering the safety profile. The description adds only the 2+ option constraint, which the schema also enforces, and says nothing about placement behavior (after/position/parentId interactions) or what a failed insert affects.

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 constraint and usage hint follow immediately after the purpose statement.

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

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

For a mutation tool with 10 parameters and no output schema, the description is thin: safety is covered by annotations and parameters by the schema, but ordering/parenting semantics and the effect of insertion are left entirely to the schema, which is adequate but not rich.

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 10 parameters, so the schema already carries the semantics (including the chaining behavior of 'after' and 'position'). The description adds no parameter-level detail, which is the expected 3 baseline 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?

The description states a specific verb and resource ('Insert a dropdown select question') and adds the key constraint (2+ options). It does not explicitly distinguish this from close siblings like editor_insertRadioQuestion or editor_insertCheckboxQuestion, so an agent still has to infer the boundary.

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 single or multi-choice from a list' gives implied usage context, but there is no when-not guidance (e.g. prefer radio for few visible options, checkbox for multi-select) despite many near-identical insert siblings.

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

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

Annotations already 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 no behavioral context beyond the question type — it does not mention that insertion mutates the form, how ordering/after-chaining behaves, or any side effects.

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

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

A single front-loaded sentence with no filler; every word earns its place.

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

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

For an 8-parameter mutation tool with no output schema, the description is minimal but the schema fully documents placement semantics, chaining, and required fields. What is missing is usage context — which question type to choose — leaving the definition adequate rather than complete.

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

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

Schema description coverage is 100% (8 of 8 parameters documented, including the $prev chaining hint and the position/after exclusivity), so the schema already carries parameter meaning. The description adds nothing about any parameter, matching the baseline 3.

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

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

States a clear verb+resource ('Insert a toggle switch question') and scopes it to yes/no or on/off responses, which distinguishes it from the many other editor_insert*Question siblings. It does not explicitly name a confused alternative (e.g. checkbox or radio), so it falls 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 is given: nothing says when a toggle switch is preferred over editor_insertCheckboxQuestion, editor_insertRadioQuestion, or the other question types. Usage is only implied by the tool name and purpose.

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 substantive content-level context beyond that: this inserts a static display table rather than an interactive question, which changes how downstream authoring treats the node.

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 discriminating fact (static table vs question), followed by a type warning and one example. No filler, and the most failure-prone detail (wrong insert type) comes first.

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

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

For a 7-param mutation tool with no output schema and full schema coverage, the description covers what an agent most needs: what it inserts, what it is not, and the row/col types. Placement behavior (after/position/parentId) is left entirely to the schema, which is acceptable but leaves a small gap for a tool whose default append is noted as 'usually wrong'.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a useful type guardrail ('rows and cols are numbers, never strings') plus a concrete example ({rows:3, cols:2, hasHeader:true}). It says nothing about after/parentId/position semantics, leaving those 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 and resource ('Insert a static content table') and immediately delimits it against the closest sibling by naming editor_insertMatrixQuestion. The parenthetical explaining that cells are author-filled text (not respondent input) makes the distinction 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?

Explicitly gives a when-not-to-use rule ('NOT a question; for rating grids respondents answer, use editor_insertMatrixQuestion'), which is genuine routing guidance. It stops short of covering placement/prerequisite context (parentId, position, formId), which lives only in the schema.

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, and the description is consistent with that (insert = creation, not destruction). However, the description adds no behavioral context beyond the annotation profile - nothing about positioning behavior, chaining via after, or what happens on failure.

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 compact sentences with the core action front-loaded and zero filler. It is arguably too sparse for a 13-parameter tool, but nothing in it is wasted.

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 creation tool with a nested object and no output schema, the description is minimal, though the fully documented schema carries most of the load. It omits the required formId/title expectation and insertion-positioning context that would help an agent call it correctly on the first try.

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 is documented in the schema, including the nuanced after/position/defaultValueFieldRef semantics. Baseline 3 applies since the description contributes no additional parameter meaning beyond the vague 'short or long text' hint at min/max.

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 text question') and scopes it to 'short or long text responses', which lets an agent distinguish it from the many sibling question-insertion tools. It does not name any sibling explicitly, 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?

'Use for names, comments, descriptions' gives implied usage context for choosing a text question over other question types, but there is no when-not guidance and no reference to alternatives like insertNumberQuestion or insertSelectQuestion. Adequate but thin.

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 safe, non-destructive, closed-world write profile, so the description only needs to add mutation-specific context. It instead says nothing about insertion behavior, the significance of the `after`/`position` interaction, or what the default append does — context the schema hints at but the description never reinforces.

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 sentence with no waste and the core action front-loaded. It is efficient but so terse that it borders on under-specification rather than optimal 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?

For a 7-parameter insertion tool sitting among dozens of sibling inserters, the description omits sibling disambiguation, placement behavior, and defaults. It relies entirely on schema text to carry completeness, which leaves the agent without routing cues.

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 nuanced after/position/parentId placement semantics, are already documented in the schema. The description adds no 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?

States a specific verb (Insert) and resource (a time picker question), which is clear. However, it does not differentiate from near-identical siblings such as editor_insertDateQuestion or editor_insertScheduleAppointmentQuestion, which an agent could easily confuse it with.

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

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

There is no guidance on when to choose a time question over a date question, schedule appointment question, or number question, nor any mention of prerequisites like an existing formId. The agent must infer usage entirely from the tool name.

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 cover the safety profile (not read-only, not destructive, not open-world). Beyond that, the description discloses that the operation is an overwrite (so an existing rule is replaced), that referenced question/page/field IDs are validated, and that a rule targeting a question requires a companion isHidden change. That is meaningful behavioral context the annotations do not 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?

Five short sentences, front-loaded with the mutation and its target, then consequences, prerequisites, and a skill pointer. Every sentence carries distinct information; 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 mutation tool with a very complex nested schema, no output schema, and annotations supplying the safety profile, the description covers overwrite semantics, ID validation, the prerequisite read, and the isHidden companion step. It does not mention error/failure behavior or return value, but with no output schema that 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% and the deeply nested logicRule structure is thoroughly documented in the schema itself (operators, action types, fieldRef vs literal, nesting depth cap). The description adds only that logicRule is a 'single replacement rule' — useful framing but not new parameter syntax. Baseline 3 is correct 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?

Specific verb+resource+scope: 'Overwrite the single conditional rule on a logic element identified by nodeId.' The word 'single' and the overwrite framing distinguish it cleanly from the sibling editor_insertLogic, which the description names implicitly by telling the agent to insert separate 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 routing: insert separate logic elements for extra rules, delete the element to remove a rule, read the document first with editor_getDocument for valid IDs, and set isHidden:true on questions referenced by a rule. It also points to load_skill("logic-rules") for deeper guidance. Nothing about when to use vs. not use 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=true, destructiveHint=false and openWorldHint=false, so the 'Read-only' sentence largely repeats structured data. The one genuinely additive trait is runtime fidelity ('same engine as the published form runtime'), but nothing is said about error behavior or whether anything is persisted.

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 and output, with no filler. 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?

With no output schema, the description does the necessary work of naming the three result categories (visibility/required/calculated), which is enough for an agent to understand the return. It stops short of describing the response shape or error handling, but the core need is met.

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%: the 'answers' property is richly documented while 'formId' has no description anywhere. The phrase 'against sample answers' loosely maps to the answers parameter but adds no detail beyond the schema, and formId is left entirely undefined.

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 (Simulate) and resource (logic rules), and states exactly what comes back: visibility/required/calculated results. This clearly separates it from siblings like editor_setLogic and editor_insertLogic, which define logic rather than test it.

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

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

The description implies the tool is for testing logic rules but never states when to reach for it versus editor_setLogic or editor_insertLogic, or any preconditions (e.g. logic must already exist). 'Uses the same engine as the published form runtime' is fidelity context, not usage guidance.

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

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

Annotations already declare non-readOnly, non-destructive, closed-world, so the safety bar is partly met. The description adds real behavioral context beyond them: whole-element replacement semantics ('not a substring or document-wide replace'), 'not valid on input/option shells', that properties are partial, and that moveTo preserves id/content. It does not address reversibility or permission requirements, so not a full 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?

Front-loaded with the core purpose and the required-call precondition, then grouped by content/properties/moveTo. The properties enumeration is dense but justified by 60% schema coverage; the block is long but each clause carries a node-type constraint or example.

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-object mutation tool with no output schema, the description covers purpose, precondition, per-field validity, moveTo usage examples, and the sibling to use for logic. 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?

Schema coverage is 60%, so the description must compensate and it largely does: it documents the two undescribed fields (isHidden, titleIsHidden) and adds cross-type validity (maxStars on rating-input, min/max/minLabel/maxLabel on linear-scale, defaultValue null clears). Much of the rest duplicates schema descriptions, capping it below 5.

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 (edit one element by nodeId) and enumerates the three editable facets (text, props, position). It clearly distinguishes itself from the insert_* siblings and from editor_formatText/editor_setLogic, which it names.

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

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

Gives an explicit precondition ('Call editor_getDocument first and copy nodeId... never guess or reuse an ID from an earlier conversation') and routes one case to an alternative ('To set conditional logic rules... use editor_setLogic instead'). Both when-to-use and when-not-to-use are covered.

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?

Beyond the readOnlyHint annotation, it discloses the Pro-account prerequisite and failure mode (UPGRADE_REQUIRED, including historical data), the all-time period behavior when dates are omitted, the semantics of totalEvents as pre-deduplication raw counts, and the unit ranges of rate metrics. That is substantial behavioral context the annotations 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?

Front-loads the purpose and return summary, then layers constraints and edge cases. Dense but each sentence (units, all-time default, upgrade gating) carries information an agent needs; it is somewhat long but not 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?

Since there is no output schema, the description supplies the response shape ({ formId, period, metrics, breakdown, totalEvents }), the meaning of totalEvents, and the upgrade error path. For a read-only analytics tool with 7 params this is complete enough to invoke 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 meaning beyond the schema: it explains that omitting both from/to yields period { from: null, to: null } (all time), states that rate metrics are 0–100 and counts are integers, and clarifies totalEvents. These are non-obvious semantics not derivable from the schema alone.

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

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

Opens with a specific verb+resource ('Get form analytics') and enumerates the exact metrics and breakdown dimensions returned. It names the sibling form_list as the way to obtain formId, so an agent can distinguish it from other form_* tools immediately.

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 routes the agent to form_list to find formId before calling, and flags the Pro-feature gating that returns UPGRADE_REQUIRED. It stops short of naming when-not-to-use alternatives, so it is clear context without full exclusion guidance.

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

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

Annotations declare 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 this a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower; the description still adds real behavior — search results are capped at `limit` with a truthful `hasMore` flag and cannot be paginated further. It stops short of describing the response shape or default ordering.

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, no filler, and the scoping/pagination constraints are front-loaded before the search caveat. Every clause carries operational 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?

With no output schema, the description carries the return-value burden and does mention hasMore and nextCursor, but it never enumerates what a form record contains or the default sort order. Adequate for a filtered list tool, with a small remaining 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 coverage is 80%, so the baseline is already 3, but the description adds genuine semantics: the null-vs-omit distinction for folderId, the fuzzy nature of `query` and its pagination limitation, and that `cursor` applies only to the unfiltered path. This is meaning beyond the field-level schema text.

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 in a workspace') plus scope modifiers (folder filter, fuzzy name query), so the agent can distinguish it from form_get or formSubmission_list. It does not explicitly name a sibling alternative, which keeps it 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?

Gives concrete routing rules: folderId=null for root-level only vs omit for all, pass `query` to search, and notes cursor pagination is only available on the unfiltered list path. It even tells the agent what to do when hasMore is true (tighten the query), 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 only declare this is a non-read-only, non-destructive, closed-world mutation, so the description carries the interesting burden and delivers: idempotency guarantees, snapshot-vs-draft republish semantics, and the warning emitted for content-blocks-without-questions. It stops short of stating permission requirements or what the call actually returns.

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?

Purpose is front-loaded, then edge cases and the next step follow in compact clauses with minimal waste. The dash-separated enumeration of idempotency rules is dense but each clause conveys a distinct behavior an agent needs, so little could be cut without losing signal.

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 the failure path, the idempotency contract, and the intended follow-up call. It omits anything about required auth or the shape of the success response, which is a minor residual gap given the tool's simplicity.

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

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

Schema description coverage is 0% for the single required formId parameter, so nothing documents its format or provenance. The description implies a form is targeted but never says how to obtain a formId (e.g. from form_list or form_create), leaving a small gap that the self-explanatory name only partly covers.

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 in the first clause ('Publish a form to make it live'), which cleanly separates it from siblings like form_unpublish, form_create, and form_update. It also names the follow-up tool (formShareLink_create) and the prerequisite editors, so the agent can place it in the workflow without reading other 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 explicit when-to-use and when-it-fails conditions: drafts publish from current content, republishing pulls the last snapshot, and forms with no editor content cannot be published until editor_insertHeader or editor_insertTextQuestion is called. It also routes the agent forward to formShareLink_create, covering both prerequisites and next steps.

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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by enumerating the returned settings surface, which is meaningful 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?

Two tightly packed sentences with zero waste; the return payload shape is front-loaded in the second sentence and can be scanned instantly. 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?

With no output schema and a single trivial parameter, the description compensates by enumerating the returned object keys ({ settings, isDefault, availableEmailDomains, defaultFromAddress, payment }), giving the agent full expectation of the response. 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?

Only one parameter (formId) with 100% schema description coverage, so the schema fully documents it. The description adds no format or sourcing guidance for the formId beyond what the schema says. 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 (Get) and resource (form settings) and enumerates exactly which settings groups are returned: notification email config, respondent emails, active/verified email domains, and Stripe payment status. This distinguishes it from formSettings_update and form_get at a glance.

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

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

Usage is implied by the name and the read-only framing, but the description never states when to call this versus form_get or formSettings_update, nor any prerequisites such as requiring a published form. Adequate but with clear routing gaps.

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

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

Goes well beyond the safe-mutation annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false): it discloses tier gating (Pro tier reminder, Business plan retention), localization side effects (subject/body edits become translatable immediately, self-notification is not translatable), mutual exclusions (redirectUrl vs allowAnotherResponse), and that submissionRetentionDays clears a builder-configured fixed deletion date.

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 routing sentence, then progressively finer detail; every block (email flows, localization, placeholders) is load-bearing for a 34-parameter tool. It is long, and some parameter-level facts duplicate the schema descriptions, but there is no padding prose.

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 34-param mutation tool with no output schema, the description covers the cross-parameter interactions an agent cannot infer (flow gating, mutual exclusions, tier requirements, where to obtain IDs). Return-value behavior is the only omission and is low-stakes for a settings update.

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 real semantics the schema lacks: the three independent email flows and their gating flags, the requirement that *To point at an email-input field ID, and most importantly the full {{variable}} placeholder vocabulary including answer-by-field-key resolution. A few lines (e.g. emailDomainId null reset) merely restate schema text.

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 ('Update form settings') and immediately scopes it to form BEHAVIOR, explicitly naming the sibling tools that handle the excluded concerns (form_update, formTheme_set, editor_*). An agent can select this tool 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?

Provides explicit routing rules: this tool for behavior, form_update for name/folder/cover/logo, formTheme_set for visual theme, editor_* for questions and content. It also states cross-tool prerequisites (emailDomainId from formSettings_get, field IDs from editor_getDocument, localization via translationDraft_get/update).

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 readOnlyHint=false, destructiveHint=false, openWorldHint=false — the generic mutation profile. The description adds real context beyond that: the publish prerequisite, the fact that a respondent-facing `url` and `availableCustomDomains` are returned, and the intended follow-up mutation. It does not describe rate limits, auth, or what happens on duplicate links, so it stops short of 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 tight sentences, front-loaded with the operation and the blocking prerequisite, then the return contents, then the follow-up call. No filler or restatement of the title.

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 create tool with no output schema, the description usefully documents what comes back (`url`, `availableCustomDomains`) and the required prior state, which covers most of what an agent needs. The remaining hole is the meaning/effect of `expiresAt` and `maxClaims`, which the description never addresses.

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 explains none of the three parameters. `expiresAt` and `maxClaims` are semantically loaded for a share link (expiry semantics, claim counting, whether 0/omitted means unlimited) and are left entirely undocumented, so the description fails to compensate for the coverage gap.

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