Formbricks MCP by usefulapi

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

Annotations only supply destructiveHint=true, which is itself ambiguous for a create operation, so the description carries most of the behavioral burden. It adds the underlying endpoint (POST /management/contacts) but says nothing about duplicate/uniqueness handling, idempotency, permission requirements, or what happens to an existing contact with the same email/userId – all critical for a contact-creation 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?

Two short sentences, front-loaded with the actual behavior. The trailing 'Formbricks v2: POST /management/contacts' is mild implementation detail that doesn't help an agent decide or invoke, but it is brief and not disruptive.

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 should ideally indicate what a successful creation returns (contact id, etc.) but does not. For a 3-parameter tool with nested attributes and a destructiveHint annotation, the definition is adequate but leaves response and duplicate-handling behavior unspecified.

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 required workspaceId, attributes, and optional environmentId are already documented in the schema. The description's mention of 'email and userId' examples echoes the schema's own attribute example rather than adding new semantics, 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 (Create) and resource (a contact) plus scope (in a workspace, from a set of attributes), so the agent knows exactly what the tool does. It doesn't explicitly differentiate from sibling tools, but since it is the only create-contact tool among its siblings, that omission is minor.

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 what the tool does but gives no guidance on when to invoke it versus alternatives, no prerequisites (e.g. required auth/permissions), and no conditions under which it should not be used. Usage is left entirely to inference 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?

The annotation destructiveHint=true already tells the agent this is a mutating operation, so the description's remaining burden is lighter, but it adds almost nothing beyond the API path note ('Formbricks v2: POST /management/webhooks'). It omits idempotency, whether duplicate URLs are rejected, auth requirements, and what the call returns, which matter for a registration endpoint.

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 the operation stated first and no padding or repetition. The trailing API-path sentence is mild metadata rather than a burden, keeping it tight overall.

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

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

For a 6-parameter, 5-required mutation with no output schema, the description covers the what but leaves the return value (e.g. the created webhook id), failure modes, and auth context unaddressed. Adequate but with clear gaps for an agent that must call it correctly.

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

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

Schema description coverage is 100%, so required fields (name, url, workspaceId, triggers, surveyIds) and optional environmentId are fully documented in the schema itself. The description adds no syntax, format, or default-value 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?

States a specific verb and resource ('Register a webhook') plus the event scope ('fires on survey events'), which cleanly separates it from siblings like formbricks_delete_webhook, formbricks_list_webhooks, and formbricks_get_webhook. 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?

The description states what the tool does but gives no guidance on when to choose it over alternatives or any prerequisites (e.g. that a webhook must be deleted via formbricks_delete_webhook before re-registering). Usage is only implied by the verb 'register'.

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 destructiveHint annotation already signals a write/destroy operation, and the description adds the non-obvious detail that the action is irreversible and the exact endpoint it maps to. It stops short of stating auth/API-key requirements or what happens to already-deleted ids.

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, no padding, with the destructive nature and the reason to use it front-loaded ahead of the endpoint trivia. Every sentence earns its place.

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

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

For a one-parameter destructive tool with annotations covering safety and no output schema, the description is essentially complete. Only fringe details (auth requirement, response on already-deleted ids) are absent.

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

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

Schema description coverage is 100% for the single response_id parameter, so the schema already carries the parameter meaning; the description only reinforces it via the singular 'one survey response'. Baseline 3 is appropriate 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 (delete) plus resource and scope (one survey response), and the endpoint line pins down exactly which API operation this is. An agent can distinguish it from formbricks_get_response, formbricks_list_responses, and formbricks_delete_webhook 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 a concrete motivating scenario — honouring a data-deletion request — which tells the agent when this tool is the right choice. It does not name an explicit alternative or state when not to use it, but for a uniquely-scoped delete operation there is little ambiguity to resolve.

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, so the safety profile is covered. The description adds no behavioral context beyond that: it does not say whether deletion is permanent, what happens to delivery history or in-flight events, or whether any confirmation/retry semantics exist. The API route mapping (DELETE /management/webhooks/{id}) is documentation trivia rather than agent-relevant 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?

Very short and front-loaded: the verb and resource appear in the first three words. The second sentence restating the REST route is mildly redundant for an agent but costs little space.

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 destructive delete with no output schema, the essentials are present and the destructiveHint annotation covers the risk. Missing is any statement of irreversibility or post-deletion state, which would matter most for a destructive operation.

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 there is a single required parameter, so the schema already explains webhook_id fully. The description adds nothing about the identifier's format or where to obtain it, 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 (Remove) and resource (a webhook), which cleanly separates it from formbricks_create_webhook, formbricks_get_webhook, and formbricks_list_webhooks by name. It does not explicitly call out those siblings or the scope of removal, but the action is unambiguous.

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

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

There is no when-to-use guidance, no prerequisite (e.g. that the webhook must be fetched first), and no alternative or exclusion stated. The agent must infer that this is the sibling to reach for when a webhook should be removed.

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 already establishes this is a safe read, so the bar is lower. The description adds only the underlying REST mapping (GET /management/contact-attribute-keys/{id}), which is mildly useful for tracing but discloses nothing about not-found behavior or auth requirements.

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

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

Two short sentences, zero filler, with the purpose front-loaded ahead of the API mapping. Nothing needs trimming.

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 would ideally say what a contact attribute key record contains or what happens when the id is unknown. For a trivial single-resource GET it is minimally serviceable, but a small gap remains.

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 the single key_id parameter already documented ('The attribute key's id.'). The description adds no format, source, or constraint information beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Fetch) and resource (a single contact attribute key), and the word 'single' implicitly separates it from the sibling list_contact_attribute_keys. It does not name the alternative explicitly, so it falls just short of 5.

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

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

Usage is only implied: 'a single ... key' suggests you call it when you already have an id rather than browsing. There is no explicit statement of when to use this versus the list endpoint, and no prerequisites or error conditions mentioned.

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 safety is covered. The description adds genuinely useful context beyond that: the v2 REST endpoint (GET /management/responses/{id}) and the payload shape (answers, metadata, completion state). It does not cover error behavior (unknown id) or auth requirements, so it stays at a solid but not rich 3.

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 no filler. The payload contents are front-loaded before the API path, which is appropriately secondary detail.

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 present, the description usefully enumerates the returned fields, partially filling that gap, and the single required parameter is fully documented in the schema. Missing only the failure mode for an invalid or inaccessible response_id.

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, and schema description coverage is 100% ('The response's id.'). The description adds no format, source, or lookup guidance for response_id beyond what the schema already states, 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 (Fetch) and resource (a single survey response) and enumerates what comes back (answers, metadata, completion state). The word 'single' clearly separates it from formbricks_list_responses without needing the schemas opened.

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 adjective 'single' implies this is the by-id counterpart to the sibling list tool, so the use case is inferable, but there is no explicit when-to-use statement, no mention of list_responses as the alternative, and no stated precondition that a known response_id 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?

readOnlyHint=true already tells the agent this is a safe read, so the description adds limited extra behavioural context. It does disclose the underlying API route, but omits whether links expire, whether calls are idempotent, or what happens if the contact/survey does not exist.

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 dense sentence with the essential purpose front-loaded, followed by a short API reference. The endpoint string is arguably redundant for an MCP agent, but it is compact and does not bloat the definition.

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 read-only tool with no output schema, the description conveys both input intent and the returned artifact (a URL). The only real gap is the absence of failure/expiry behaviour, which is minor at this 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 description coverage is 100%, with both survey_id and contact_id documented, so the baseline is 3. The description reinforces the pairing ('one contact' for 'a survey') but adds no syntax, format, or ID-source 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?

States a specific verb (get) and resource (personalised survey URL for one contact) and immediately clarifies the scope as a single-contact link, which implicitly separates it from formbricks_get_survey_segment_links. An agent can distinguish this 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?

The clause 'the link you send so their response is attributed to them' communicates the use context (per-contact response attribution), which is useful implied guidance. However, it never states prerequisites (e.g. contact must already exist) or points to the segment-links alternative when a bulk link is needed, so usage is only implied.

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

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

readOnlyHint=true already establishes this as a safe read. The description adds that it returns a link per contact in a segment, which implies a potentially large result set, but says nothing about pagination defaults, result-size limits, or rate-limit behavior for a bulk retrieval.

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 tight sentence with the purpose front-loaded, followed by the endpoint reference. No filler, though the raw endpoint path is of marginal value to an agent that already has the tool name.

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 list tool with no output schema, the description conveys what is returned (personalised URLs per contact) and the schema covers every parameter. It is nearly complete, with only the pagination behavior of the returned set left implicit.

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 four parameters (including skip/limit paging semantics) are fully documented in the schema. The description adds no syntax or format detail 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 ('Get') and resource ('personalised survey URLs for every contact in a segment'), plus the exact REST endpoint. The plural 'for every contact in a segment' implicitly distinguishes it from the sibling formbricks_get_survey_contact_link, though it never names that 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?

The phrase 'how you run a targeted send' hints at the use case but gives no explicit when-to-use, when-not, or alternative routing. An agent must infer that this is the segment-wide bulk counterpart to the single-contact link tool.

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 already tells the agent this is a safe, non-mutating read, so the description's burden is lower. It usefully discloses the shape of what comes back (URL, triggers, bound surveys), but adds nothing about error behavior for a missing id, permissions, or auth requirements.

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

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

Two tight sentences with the payload description front-loaded. The trailing 'Formbricks v2: GET /management/webhooks/{id}' is largely orientation detail that restates the path already implied by the id parameter, but it is brief and not harmful.

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 compensates by naming the returned fields, which is the main thing an agent needs. Nothing critical is missing for a simple single-resource read, though id sourcing and array/cardinality details for triggers and surveys are left unspecified.

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 and schema coverage is 100%, so the schema fully documents webhook_id. The description adds no format, sourcing, or lookup hints (e.g. that the id comes from list_webhooks), leaving the baseline 3 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?

Names a specific verb (Fetch) and resource (a single webhook) and enumerates the payload it returns (URL, triggers, bound surveys). The singular 'a single webhook' implicitly separates it from the list_webhooks sibling, but that sibling is never named, so the differentiation is only inferred.

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 'a single webhook' — the agent can infer this is the lookup-by-id tool rather than the enumerator. There is no explicit statement of when to reach for this versus formbricks_list_webhooks, nor any prerequisite (e.g. needing an id obtained from the list call).

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 readOnlyHint=true annotation already establishes this as a safe, side-effect-free read. The description adds the HTTP method and path, which is useful orientation, but says nothing about auth requirements, rate limits, latency, or how failures surface.

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, purpose front-loaded, endpoint detail second. No filler and nothing that could be trimmed.

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-parameter, no-output-schema probe, the description covers what the agent needs to call it. It could still say what a success or failure looks like, which leaves a small 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?

The tool takes zero parameters, so the baseline is 4. The schema is empty and the description correctly implies no inputs are needed, though it adds no parameter-level meaning to convey.

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 that the Formbricks API is reachable, plus the concrete endpoint GET /health. This is clearly distinguishable from every sibling, which are all resource-level CRUD operations.

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 (a connectivity/preflight probe), but the description never says when to call it, whether it should precede other calls, or what it means if it fails. There are no true alternatives among the siblings, so the omission is mild but real.

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 annotation readOnlyHint=true already declares the safety profile, and the description adds useful domain context ('schema of what you know about a contact') and the API endpoint. However, it does not disclose return format, pagination behavior, or auth/rate-limit considerations beyond what the annotation provides.

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 waste, front-loading the tool's purpose and then adding the API endpoint as secondary context. Every sentence earns its place.

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

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

For a simple list tool with no output schema and full schema coverage on parameters, the description is nearly complete. It could mention pagination briefly, but the schema already covers that, so no critical invocation information 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 six parameters thoroughly. The description adds no parameter-level semantics beyond what the schema provides, making 3 the appropriate 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?

The description states a specific verb and resource ('List the contact attribute keys') plus scope ('defined in an environment') and clarifies what the keys represent. It does not explicitly distinguish itself from the singular sibling get_contact_attribute_key, so it falls just 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?

There is no explicit guidance on when to use this tool versus alternatives such as get_contact_attribute_key, nor any prerequisites or exclusions. Usage is only implied by the name and description.

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

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

The readOnlyHint=true annotation already tells the agent this is a safe, non-mutating read. The description adds the backing endpoint (GET /organizations/{organizationId}/users), which reinforces the read-only nature and helps with traceability. It does not disclose pagination behavior, default page size, or whether an empty result differs from an error, so added context beyond the annotations is modest.

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 capability front-loaded and the optional filtering qualifier immediately after. The trailing API endpoint note is mildly redundant but short and aids the agent in mapping the call to the Formbricks v2 API.

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

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

For a simple read-only list operation with 100% schema coverage and an explicit readOnlyHint annotation, the description supplies what the agent needs to select and call it. No output schema exists, but the description need not enumerate return fields for a straightforward list endpoint; only a note on pagination defaults would improve it.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including the skip/limit paging semantics and the id/email filters. The description echoes the id/email filtering but adds no format details (e.g., UUID expectations) or interaction rules (id and email together). Baseline 3 is appropriate when the schema carries the detail.

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 users in an organisation') and adds the optional filters by id or email, which is far more than a restatement of the name. The resource noun ('users in an organisation') cleanly separates it from siblings like list_roles, list_teams and list_webhooks, though it never names or contrasts 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?

The description indicates that lookups by id or email are optional refinements of a full list, which implies the basic usage pattern. It gives no when-not guidance, no prerequisites, and no explicit alternatives (there is no competing 'list users' sibling, so alternatives are moot). Usage is implied rather than spelled out.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's burden is reduced. It adds the concrete backend mapping (Formbricks v2: GET /management/responses) but says nothing about pagination behavior, default page size, or the shape/volume of what comes back – useful context that is absent.

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

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

Three short, front-loaded sentences with no filler; the core purpose leads and the endpoint detail trails. The endpoint sentence is marginally dev-facing rather than agent-facing, which keeps it short of 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 nine-parameter listing tool with no output schema, the description covers what it returns at a high level ('the answers people gave') but not the record shape or pagination semantics the agent needs to page correctly. Adequate but with a clear gap given the absent 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 description coverage is 100%, so the schema already documents all nine parameters, including paging and sort. The description reinforces the three filter axes (survey, contact, date window) but adds no syntax or format detail 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 and resource ('List survey responses') and immediately scopes it ('optionally narrowed to one survey, one contact or a date window'). It also carves itself out from the sibling read tools by declaring 'This is the main read: the answers people gave', which separates it from formbricks_get_response and formbricks_delete_response.

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

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

The phrase 'This is the main read' implies when to reach for this tool, and the narrowing options signal the filter use cases. However, it never names an alternative (e.g. use formbricks_get_response for a single response) or states an exclusion, so the guidance stays 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the API endpoint mapping but no further behavioral detail such as whether the result is static/enum-like, requires org admin scope, or is cached. Adequate but adds little beyond the 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?

Two short sentences, zero filler, purpose front-loaded before the endpoint reference.

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 list tool with annotation coverage, the description is nearly sufficient. It could note that the response is a fixed set of role names/IDs (which matters since no output schema exists), but nothing required 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate.

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?

Clear specific verb+resource: 'List the roles that can be assigned to organisation users', plus the mapped v2 endpoint GET /roles. The resource is unambiguous and easily told apart from siblings like formbricks_list_teams or formbricks_list_organization_users, though the description never explicitly states that distinction.

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

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

The phrase 'roles that can be assigned to organisation users' implies the use case (resolving valid role values before assigning a user), but there is no explicit when-to-use or when-not-to-use guidance and no named alternative.

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 safety is covered. The description adds the underlying REST endpoint (GET /organizations/{organizationId}/teams), which is mildly useful context but discloses nothing about result size, paging defaults, or permissions.

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 the primary purpose front-loaded and no filler. The API-path sentence is arguably redundant for an agent but is compact and harmless.

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 low-complexity read-only list tool with full parameter documentation, the description is nearly sufficient. The missing piece—what the returned team objects contain—is minor, though there is no output schema to compensate.

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 skip, limit, order, sortBy, and organization_id are all documented in the schema. The description adds nothing parameter-specific, which is the expected baseline when the schema does the work.

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 teams) scoped to an organisation, which is clearly distinct from sibling list tools such as list_organization_users, list_roles, and list_webhooks. It does not, however, explicitly contrast itself with those siblings.

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

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

The description gives no when-to-use context, no prerequisites, and no alternatives or exclusions. An agent must infer that this is simply the way to enumerate teams.

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 the safety profile is covered. The description adds the useful context that these webhooks fire on survey events and cites the underlying endpoint, but says nothing about pagination behavior or return 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?

Two compact sentences with the core purpose front-loaded and the endpoint reference appended; no filler or repetition.

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

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

For a read-only list tool with no output schema and fully documented parameters, the description covers what an agent needs to select and call it. Pagination/return details are absent but not essential given 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% with all five params (skip, limit, order, sortBy, surveyIds) documented inline. The description only reinforces the surveyIds filter, adding nothing new beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the webhooks') plus scope ('configured to fire on survey events') and the filtering capability. This separates it from get_webhook/create_webhook by implication, though it never names a sibling 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?

Signals the optional survey filter ('optionally filtered to specific surveys'), which implies when the surveyIds parameter is relevant, but gives no explicit when-to-use vs. get_webhook for a single webhook or when-not guidance.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds that the lookup is scoped to the currently configured key and cites the backing endpoint (GET /me), but discloses nothing about rate limits, error behavior when the key is invalid, or response 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?

One front-loaded sentence states the return value and the practical motivation, followed by a terse endpoint reference. No filler, and the most decision-relevant information 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 zero-argument read-only tool with no output schema, the description supplies enough: what it returns and why an agent would call it. It stops short of describing the returned fields (project id, environment id, names), which would have closed the last 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?

The tool takes zero parameters (100% coverage of an empty schema), so there is nothing to disambiguate; baseline for no params applies. The description correctly conveys that the only input is the ambient x-api-key credential.

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

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

States a specific verb and resource: it returns the project and environment tied to the configured x-api-key. This identity/resolution purpose is clearly distinct from every sibling (create/delete/list/get of other resources), so an agent can distinguish 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?

Positions the tool as 'the fastest way to find the workspace and environment ids the other tools need,' which tells the agent to call it before tools that require those ids. It gives clear context but names no explicit alternative or exclusion condition.

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