formhaus-mcp

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

readOnlyHint=true already tells the agent this is a safe read. The description adds genuinely useful behavioral context beyond annotations: it is a reference lookup rather than an action, and it enumerates the breadth of what the returned reference includes (including less obvious topics like step/route semantics, overlay addresses, adapters), which sets expectations for the payload. It doesn't describe output structure, but an output schema exists to carry that.

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 imperative to call it first is front-loaded, and the alternatives are stated before the long feature enumeration. The second sentence is a dense list, but each item names a distinct capability domain an agent would otherwise have to discover by trial, so the length is largely earned; it is slightly list-heavy for a two-sentence description.

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-arg read-only reference tool with an output schema, the description covers what it returns, when to call it, and what to use instead for the two adjacent tasks. Nothing an agent needs in order 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?

Zero parameters, so per the baseline this scores high; the description correctly spends no words on argument syntax. Its enumeration maps to the content the call returns rather than to inputs, which is the right use of description space for a no-arg tool.

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 and resource ('Lists what a Formhaus definition supports') and enumerates the reference domains covered (field types, sections, groups, validation rules, actions, translation, adapters). It also distinguishes itself from two siblings by name, so an agent can tell it apart from example_definitions and validate_definition 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?

It explicitly states the trigger ('Call this first, before writing or editing a definition') and routes to the two alternatives with their selecting conditions: example_definitions for whole working forms to copy, validate_definition for checking a finished definition. No inference is required.

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=true (safe read); the description adds the branching behavior (no id = list bundled examples, with id = return that definition) that the annotation does not cover, plus the intended workflow after retrieval. It does not describe auth needs or pagination, 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?

Front-loaded with the use case, then the behavioral contract, then the follow-up action. Dense but every clause (examples of patterns, the capabilities contrast, the validate step) earns its place; the multi-clause semicolon sentence is slightly heavy.

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 one-optional-param read tool with an output schema and readOnlyHint, the description covers when to use it, what each invocation mode returns, and the intended next step. Nothing an agent needs to call it correctly is missing, and return shape is delegated appropriately to the output schema.

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

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

Schema coverage is 100% for the single 'id' parameter, including its example value and the omit-to-list semantics, so the schema carries this dimension. The description restates the with/without-id behavior rather than adding new parameter meaning, which is the baseline-3 case.

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

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

States a specific purpose (fetch a bundled example definition to start from or copy) with a clear verb+resource and explicitly contrasts it with the sibling 'capabilities' (lists every option but shows no complete form). An agent can distinguish this tool from its siblings 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?

Names the trigger condition ('when you need a working form to start from or a pattern to copy, such as multi-step forms, branching routes, conditions or translations') and names the alternative it is not for ('capabilities lists every option but shows no complete form'). It also routes to the correct follow-up sibling, 'validate_definition'.

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?

Given readOnlyHint=true, the description resolves the ambiguity an agent could otherwise have from the word 'applies': it returns the repaired definition and explicitly tells the caller to save it, so nothing is persisted server-side. It further discloses a safety guarantee (safe fixes never change behavior beyond the repair), the exact return shape, and why some fixes are withheld.

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 trigger condition, then the fix classes, then the return contract, then the next action — a sensible order. Slightly overpacked as a single paragraph, and 'the same as validate_definition returns for the repaired definition' is a double-clause that could be tightened.

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

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

Even though an output schema exists, the description names the returned fields and their meaning (definition, applied in order, valid, remaining issues), explains the issues[].fixes channel, and states the required next step. For a one-parameter tool with full schema coverage, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single 'definition' parameter already carries a thorough inline description with the schema URL and shape summary. The tool description adds no syntax or format guidance for the parameter beyond the defect examples, 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 ('applies every safe fix') and resource (a Formhaus definition), and enumerates the concrete defect classes it repairs (misspelled property, missing id/key, empty label, duplicate key, missing submit button). It is unambiguously distinguished from its closest sibling 'validate_definition', which only reports.

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 trigger is explicit: 'Call this when validate_definition reports issues with safe fixes.' It also draws the boundary against the alternative path — unsafe fixes stay in issues[].fixes and must be applied by hand — and closes with the follow-up step ('Save the returned definition, then fix the remaining errors').

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds substantial context beyond them: required FORMHAUS_API_KEY credential types (account key vs. agent key), newest-first ordering, and the security caveat that values are untrusted user input. This is exactly the extra behavioral disclosure the dimension asks for.

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 auth, return shape, pagination, and the injection warning last. Nearly every sentence earns its place, though it reads as one long run-on paragraph that could be broken up.

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

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

An output schema exists so return values needn't be spelled out, yet the description still covers auth, ordering, pagination, and untrusted-data handling. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds flow-level meaning the schema cannot: it links limit/cursor to the pagination contract and next_cursor's presence/absence. The limit range and default largely repeat the schema, keeping it from a 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 precise verb+resource (read submitted answers for one form) and immediately distinguishes itself from the sibling list_forms, noting that list_forms gives only the total count. An agent can choose between them 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?

Explicitly contrasts with list_forms and explains the pagination loop: call again with next_cursor for older submissions, and absence of next_cursor means no more pages. Both the when-to-use and the when-to-stop conditions 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 and openWorldHint, and the description adds substantial context beyond them: the secret is masked, the return payload contains URL plus masked signing secret, and it requires an account key (fh_live_...) while agent keys get owner_key_required. Auth behavior and return content are disclosed rather than left to inference.

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, then routing to alternatives, then return and auth details across three dense sentences with no filler. Every clause carries decision-relevant 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?

Covers purpose, alternatives, return content, and the account-key auth requirement — the operational facts an agent needs for a one-parameter read tool. An output schema exists and is also summarized, so nothing material 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 single form_id parameter is fully documented in the schema (10-character id from publish_form/list_forms), so the description adds no parameter-level syntax or format detail. 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 and resource ('check where the webhook of a form posts') and immediately scopes it against two siblings by name. An agent can distinguish this from reveal_webhook_secret and update_form_settings 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 explicit routing rules: use this for the masked secret, call reveal_webhook_secret when the receiving server needs the full one, and update_form_settings to set or remove the URL. Both alternatives are named with the condition that selects them.

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

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

Annotations only say readOnly and openWorld; the description adds real behavioral context beyond them — newest-first ordering, the account-key vs agent-key visibility difference, the FORMHAUS_API_KEY requirement, and the two possible status values. These are exactly the traits an agent needs to predict the result 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?

Front-loaded with the routing instruction, then ordering, then the returned fields, then auth scope — a sensible priority order with no filler sentences. It is dense and slightly long, partly because the field list duplicates the output schema, which keeps it off a 5.

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

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

For a no-param list tool with an output schema, the description covers purpose, alternatives, ordering, auth scope, and status semantics; the field enumeration is redundant with the output schema but harmless. Nothing needed 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?

There are zero parameters, so the baseline is 4; the 100% schema coverage confirms nothing is required. The description correctly adds no parameter narrative because there is nothing to parameterize.

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 (lists every form the key reaches) and explicitly separates itself from the sibling get_submissions, which it names. An agent can pick between list_forms and get_submissions 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 explicit when-to-use conditions: call this to obtain a form_id for get_submissions, publish_form, update_form_settings or get_webhook; call get_submissions instead to read one form's answers. That is a complete routing rule with an exclusion.

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

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

The description adds substantial behavioral context beyond the annotations: returned fields, unclaimed-form limits, claim URLs, expiration, API-key handling, warnings, and environment configuration constraints. The write-oriented behavior aligns with readOnlyHint=false and openWorldHint=true.

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 call condition and create/version distinction, then moves into returns, key behavior, and definition rules. It is long and dense, but most content is operationally useful for a complex publishing tool; only minor tightening would improve it.

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 write operation, open-world annotations, rich input schema, and output schema, the description is complete enough to call correctly. It covers prerequisites, key requirements, return expectations, unclaimed-form behavior, errors, and definition constraints.

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 already 100%, so baseline is 3, but the description adds meaningful authoring semantics for the definition parameter: minimal valid shape, field and step rules, allowed and refused types, validation constraints, size limits, and condition syntax. It also clarifies form_id create-versus-version behavior 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 and resource: publishing a form live, with explicit distinction between creating a new form (no form_id) and publishing a new version of an existing form (with form_id). It also distinguishes this from validate_definition by saying to call it after validation passes.

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 usage guidance: call after validate_definition passes, and call when the user needs a working form such as contact, waitlist, signup, survey or feedback without a backend. The create-versus-version behavior is also clearly conditioned on form_id.

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 annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by disclosing the credential class required (account key fh_live_...), the exact failure mode for the wrong key class (agent keys answer owner_key_required), and handling obligations (store as server-side secret, never print or commit). These are operationally decisive details the structured fields cannot 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 every clause earns its place: usage, alternative, return format, auth requirement, error case, and handling rules. It leads with the usage constraint rather than the purpose verb, which is a mild front-loading inversion but still readable in one pass.

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

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

An output schema exists, so return values need no prose, and the description still covers the one thing that matters most for a secret-revealing tool: who may call it, how the wrong credential fails, and how to handle the returned value. Nothing an agent needs to call this safely 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 single form_id parameter is fully documented in the schema, including the 10-character format and where it comes from. The description adds no parameter-level information, 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 — 'Returns the full webhook signing secret (whsec_...)' — and immediately distinguishes itself from the sibling get_webhook, which returns only the URL and a masked secret. An agent can pick between the two 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?

Explicit when-to-use ('only while setting up the server that receives the webhook of a form') and when-not ('get_webhook ... is enough for anything else'), naming the alternative and the condition that selects it. Nothing 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?

readOnlyHint=true is consistent with a simulation, and the description adds substantial context beyond annotations: it discloses that custom validators, onStepValidate and lifecycle hooks are not run, documents next/back/skip refusal rules, autoAdvance behavior, and error handling when the definition is invalid. This is unusually thorough for a tool whose annotations only signal read-only.

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 the validate_definition dependency before diving into mechanics; every sentence carries operational detail. It is dense and long, but the length is justified by tool complexity rather than padding.

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

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

Despite having an output schema, the description still explains the return shape (visited/skipped paths, action trace, validation errors for visited steps, wouldSubmit, submit payload, overlayIssues), covering the mutation/simulation semantics an agent needs. Nothing material is missing for a headless form-runner.

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 contributes meaning beyond the schema: it explains how a group answer maps to an array of item objects with an example, and how action sequencing semantics (refusal, autoAdvance, skip submission) affect the run. It stops short of exhaustively documenting every parameter, which the schema already does well.

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 and resource ('check branching, routes, skip and conditional fields by stepping through the form like a user') and explicitly distinguishes itself from sibling validate_definition, which 'checks only the structure.' An agent can route between the two 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 the sequencing condition explicitly ('Call this after validate_definition passes') and the division of labor with the alternative tool. It also covers the default path when actions are omitted, so both the with-actions and without-actions modes are addressed.

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 readOnlyHint: it says the template never marks anything as translated, that revision/review state must be stored separately, and that on invalid definitions it returns ok: false with validation issues. That is exactly the extra context annotations don't 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?

The trigger, the return shape and the translate-then-save workflow are front-loaded and every sentence adds information. It is a dense single block, though, and could be split for easier scanning.

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 tool with nested JSON output, an existing output schema, and 100% parameter coverage, this description covers the workflow, the edit rules (translate values only, keep nesting and placeholders), and the error case. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so lang/prefix/catalog/definition are already documented. The description clarifies how results are consumed (overlay as locale prop, file naming) but adds little parameter-level meaning beyond the schema baseline.

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

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

States a specific action and resource: it returns the translation skeleton/overlay of a definition for one language. It also names the downstream consumer (simulate_path accepts the overlay), which separates it cleanly from validate_definition and fix_definition.

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 trigger ('when the form needs another language, once per language'), explicit follow-up step (pass overlay to simulate_path), and an explicit when-not with alternative ('when the app has its own keys, such as Lokalise keys, put them in i18n objects ... instead').

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

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

Annotations cover the safety profile (non-destructive, idempotent, open-world), and the description adds substantial context beyond them: partial-update semantics ('Send only the settings to change; omitted ones stay'), the exact auth requirement and its error (owner_key_required), the not-found behavior for unclaimed forms, secret creation on first webhook set, SSRF-style address refusals, and the paused_by_moderation state. This is unusually rich disclosure for a mutation 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?

Front-loads purpose, routing, auth and partial-update semantics, then breaks each setting into a scannable bullet with an example payload. It is longer than strictly necessary: the closing paragraph on receiver-side signature verification (header format, 5-minute skew, constant-time compare, dedup) describes the consumer's implementation rather than this tool, which is useful context but adds bulk.

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

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

An output schema exists, so return values need not be spelled out, yet the description still names the returned fields and the masked webhook_secret. Combined with auth requirements, partial-update behavior, per-field semantics, and the error-recovery instruction, an agent has everything needed to call this correctly on the first attempt.

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-parameter descriptions and enums, so the baseline is 3. The description still adds meaning beyond the schema: that private/loopback/link-local/cloud-metadata URLs are refused, that setting a URL creates a new signing secret, and the exact milestone thresholds tied to notify_mode. It does not add much on form_id or success_message 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?

States a specific verb+resource ('change how a published form behaves without touching its fields') and enumerates exactly which settings are in scope: webhook, notifications, success message, redirect, pause/resume. It explicitly distinguishes itself from publish_form for field changes, so an agent can separate the two without reading 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?

Gives explicit when-to-use routing ('To change fields, publish a new version with publish_form and form_id instead') and points to reveal_webhook_secret as the alternative for retrieving the full secret. It also states the prerequisite credential type (account key fh_live_...) and the failure mode for agent keys and unclaimed forms, which is exactly the guidance an agent needs before calling.

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=true; the description adds real behavioral context by explaining what 'error' versus 'warning' means (errors cause engine rejection), listing representative causes, and stating the iterate-until-clean workflow. The return shape is partly duplicated from the output schema, which caps it just below the top.

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?

Well front-loaded: purpose, timing, return shape, then the error/warning taxonomy. The long enumeration of warning cases is informative for interpreting output but is bulkier than strictly needed for tool selection, costing some 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?

Output schema exists, so return values needn't be re-explained, yet the description still covers error semantics, the repair loop, and the escape hatch to fix_definition. An agent has everything needed to call it, interpret results, and act on them.

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

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

There is one parameter and schema coverage is 100%, with the schema description itself explaining the object-or-JSON-string form and the definition shape. The prose adds no syntax or format detail beyond that, 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: checks a Formhaus form definition against the JSON Schema and the engine. It explicitly contrasts its role with simulate_path (which checks user flow), so an agent can distinguish the two 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?

Gives explicit timing ('after writing or editing a definition and before simulate_path or publish_form'), names the alternatives, and routes to fix_definition for batch repairs. The when-to-use and when-to-use-something-else are both spelled out.

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