formhaus-mcp

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

The readOnlyHint annotation already establishes that this is a safe, non-mutating lookup. The description adds genuine context beyond that: it is a full capability reference intended to be consulted before authoring, with an output schema available for return-value details. It does not discuss any limits or caching, but for a no-arg read-only reference tool little more is needed.

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?

Roughly three sentences, each doing distinct work: the call-first directive with alternatives, the coverage list, and the routing notes. The enumeration of coverage areas is long but earns its place by telling the agent whether this reference answers its question. Slightly list-heavy rather than wasteful.

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

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

For a zero-parameter read-only reference tool with an output schema, the description covers purpose, timing, sibling alternatives, and a migration resource pointer. Nothing an agent needs in order to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is no parameter surface for the description to clarify or omit.

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 ('Lists what a Formhaus definition supports') and enumerates the coverage areas, so the agent knows exactly what reference material it returns. It also explicitly names what it is not: 'example_definitions gives whole working forms to copy instead' and 'call validate_definition 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?

Gives an explicit trigger ('Call this first, before writing or editing a definition'), a stated alternative for a different need (example_definitions for copyable forms), a different alternative for checking results (validate_definition), and a resource pointer for migration. Nothing about when or when-not 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 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?

readOnlyHint=true only tells the agent this is non-mutating; the description adds far more — the exact return tuple, the guarantee that safe fixes never change form behavior beyond the repair, that unsafe fixes are deliberately withheld, and crucially that the tool does not persist so the caller must 'Save the returned definition'. That last point resolves the subtle tension between a mutating name and a read-only annotation.

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 condition is front-loaded correctly and every sentence carries information. It is one dense paragraph with a long example enumeration, which is slightly run-on, but there is no padding 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?

An output schema exists, yet the description still explains the specific fields that matter (definition, applied, valid, issues) and the safe/unsafe split the output schema cannot express, then closes the loop with the next action. For a repair tool feeding a validate loop, nothing an agent needs 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 definition parameter is exhaustively described in the schema, so the baseline would be 3. The description still adds semantic meaning not in the schema — the criteria distinguishing a safe fix from an unsafe one (e.g. 'pointing a condition at a field two edits away') — which tells the agent what kind of input this tool can actually repair.

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 (apply safe fixes / fix) plus a named resource (Formhaus definition), with a concrete enumeration of what counts as a safe fix. It explicitly frames itself relative to validate_definition, so an agent can separate the two siblings 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 exact trigger ('Call this when validate_definition reports issues with safe fixes'), names the alternative and its output, and draws the boundary of when NOT to expect a fix ('Unsafe fixes ... stay in issues[].fixes for you to check and apply by hand'). 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?

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?

Annotations only declare readOnlyHint=false and openWorldHint=true, so the description carries the rest and does so richly: unclaimed-form limits (3 per key, 7-day expiry, 100 submissions, redirect_url ignored), key handling and where the key must live, error-recovery behavior, and upgrade-URL surfacing. This is well beyond what the 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?

Core purpose is front-loaded in the first sentence, but the body sprawls into a full form-definition authoring guide that largely duplicates the definition parameter's schema description and overlaps with validate_definition/example_definitions. Several sentences do not earn their place in this tool's 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 high-complexity, open-world mutation tool, everything an agent needs is present: modes, prerequisites, key/auth requirements, limits, error handling, and destructive/expiry consequences. The return-value listing is redundant given the output schema, but nothing required 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 non-schema semantics: the create-vs-new-version meaning of form_id, that a new version keeps form_id/endpoint/links, and authoring constraints (32 KB, 100 fields, refused types, field/step exclusivity). It edges above baseline, though much of the definition-rule content restates what the schema description already 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+resource ('put the form live on Formhaus Cloud') and precisely distinguishes two modes of operation: no form_id creates a new form, with form_id publishes a new version. It also names the sibling that must precede it (validate_definition), so an agent can place it in the workflow without opening another 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 prerequisite ('call this after validate_definition passes'), explicit trigger ('when the user needs a working form ... without writing a backend'), and explicit alternative behavior based on form_id presence. The routing decision is fully specified rather than inferred.

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

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

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?

Annotations declare readOnlyHint=true, and the description adds rich behavioral detail beyond that: it runs a headless FormEngine, discloses that custom validators and lifecycle hooks are not run, explains action semantics such as when next is refused or skip is allowed, and describes error returns and overlay handling.

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

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

The description is front-loaded with the most important routing guidance and every major sentence carries useful information. It is somewhat long because it details return values that are already likely covered by the output schema, which is a minor redundancy 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?

Given the tool's complexity, the description is exceptionally complete: it covers prerequisites, simulation behavior, explicit exclusions, error cases, overlay support, and return shape. An agent has everything needed to invoke it correctly and interpret the result.

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?

With 100% schema description coverage, the schema already documents all four parameters, so the baseline is 3. The description adds meaningful semantics beyond the schema, notably the group answer format as an array of item objects (e.g. { "participants": [{ "name": "Ada" }] }) and the nuanced behavior of actions during simulation.

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 ('simulate a path through a form') and explicitly contrasts its purpose with validate_definition ('validate_definition checks only the structure'). An agent can distinguish this tool from all siblings 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 gives a clear precondition ('Call this after validate_definition passes'), a positive use case (checking branching, routes, skip and conditional fields), and names the alternative it is not. It also explains the fallback behavior when no actions are supplied.

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, so the description must carry the rest and does: it states the tool never marks anything as translated, that revision/review state lives elsewhere, and that invalid definitions return ok: false with validation issues. It does not, however, cover rate limits, size constraints, or what happens with an unsupported language code.

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 and return shape, and each sentence carries information. The block runs long as a single unstructured paragraph and mixes in post-call translation instructions, which slightly dilutes the tool-selection 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 read-only generator with an output schema already present, the description still covers the error contract, the i18n-keys alternative, and what to do with the returned overlay. Nothing an agent needs to select or 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 description coverage is 100%, so the schema already documents lang, prefix, and definition in detail (including the prefix=false behavior and the 'i18n' hint). The description adds only the tangential note about Lokalise-style keys, 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?

Names a specific operation (produce the translation skeleton/overlay of a definition for one language) and enumerates what comes back: overlay, file, and slots with addresses, keys, placeholders, and source hashes. It is clearly distinguishable from siblings such as validate_definition, fix_definition, and simulate_path.

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 says when to call it ('when the form needs another language, once per language') and names the condition that selects an alternative ('When the app has its own keys, such as Lokalise keys, put them in i18n objects of the definition exactly as given instead'). It also routes the output to simulate_path, covering the downstream step.

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

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

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 goes far beyond that by specifying the return shape { valid, issues }, the difference between errors (engine rejects the definition) and warnings (likely mistakes), enumerated error codes, the repair mechanism (RFC 6902 JSON Patch with a 'safe' flag), and the re-validate loop after fixing.

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 call-order guidance and the return contract before the long enumerations of error and warning codes. The code lists are dense and somewhat verbose but each example earns its place by telling the agent what a rejection actually looks like.

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 and the description still summarizes the return value; for a single-parameter validation tool with annotations covering safety, nothing an agent needs to call it correctly or interpret the result 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 'definition' parameter carries an extensive inline schema description (top-level keys, field shape, condition operators, validation rules), so the description need not compensate. The description's phrasing ('after writing or editing a definition') adds workflow context but no new parameter syntax.

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 (validates a Formhaus form definition) and explicitly distinguishes itself from siblings: it checks structure and engine rules 'while simulate_path checks how a user moves through the form.' An agent can separate it from simulate_path, fix_definition and publish_form 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 sequencing ('after writing or editing a definition and before simulate_path or publish_form') and names the alternative paths, including 'To apply every safe fix at once, call fix_definition.' When-to-use, when-not-to-use and the alternative are all present.

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