formbricks

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

Annotations supply only destructiveHint=true, so the description carries the rest of the behavioral burden. It does not disclose idempotency/duplicate handling, permission requirements, or side effects of creating a contact in a workspace — significant gaps 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?

Two short sentences, front-loaded with the core purpose. The endpoint reference is secondary but adds a small amount of orientation; nothing is wasted.

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

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

Adequate for a simple 3-parameter create tool with no output schema: parameters and purpose are covered. However, it omits behavioral details like duplicate handling and permissions that an agent would need for a mutation.

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 workspaceId, attributes, and environmentId. The description's attribute examples (email, userId) largely repeat what the schema already states, 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 ('Create a contact in a workspace from a set of attributes') with concrete attribute examples. It is clearly distinct from the sibling write tool create_webhook, though it does not explicitly reference alternatives.

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

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

No guidance on when to use this versus alternatives, no prerequisites, and no mention of what happens on duplicate contact creation. The only extra context is the REST endpoint mapping (v2 POST /management/contacts), which is not usage guidance.

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

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

Annotations supply destructiveHint=true, so the safety profile is partly covered, but the description adds almost no behavior beyond that — no auth/permission requirements, no idempotency or duplicate-URL behavior, and no note that registration begins outbound POST traffic to the target URL. The API path (POST /management/webhooks) is the only extra detail and it is incidental.

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

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

Two compact sentences with the core action front-loaded and no filler. The endpoint sentence is marginally useful for debugging but is not strictly needed.

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) creation tool with no output schema, the description is thin: it never says what is returned (e.g., a webhook ID) or what the caller should do next. The schema carries the input burden fully, so this is adequate but not complete.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema (including the useful 'empty array for all surveys' note on surveyIds). The description adds nothing about parameter meaning, so the baseline 3 applies.

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

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

The description gives a specific verb+resource ("Register a webhook") plus scope ("fires on survey events"), which cleanly separates it from list/get/delete webhook siblings. It stops short of naming those siblings or the alternatives explicitly, but the purpose is unmistakable.

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

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

There is no guidance on when to register a webhook versus using existing ones, no prerequisites, and no mention of what happens if a webhook for the same URL already exists. The only contextual clue is the API endpoint path, which is not usage guidance.

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

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

Annotations already declare destructiveHint=true, but the description adds meaningful context by explicitly stating the operation is 'Irreversible' and naming the underlying API endpoint. It does not cover auth requirements or response format, but the safety profile is well communicated.

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: the action and irreversibility are front-loaded, followed by the use case and API mapping. 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 complete schema coverage and a destructiveHint annotation, the description supplies the key missing behavioral fact (irreversibility) and an endpoint reference. It is complete enough to invoke safely, with only minor room for auth or rate-limit notes.

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 parameter is already documented as 'The response to delete.' The description adds no syntax, format, or sourcing detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Delete one survey response') with clear scope ('one'). It is trivially distinguishable from siblings like formbricks_get_response and formbricks_list_responses.

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 when-to-use condition ('use it to honour a data-deletion request') but does not name alternatives or explicit when-not conditions. For a single-purpose destructive tool with no competing sibling, this is adequate context.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the REST endpoint detail (Formbricks v2: GET /management/contact-attribute-keys/{id}), which is minor context, but says nothing about error behavior for a missing id or what the response contains.

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 action and resource. The endpoint reference is arguably redundant with the tool name but 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 simple single-resource read with one fully documented parameter and readOnlyHint annotations, the description is sufficient; no output schema is needed to explain return values. Only the missing error/not-found behavior keeps it from a 5.

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 key_id parameter is fully documented in the schema, so the description adds no parameter meaning beyond it. 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 (Fetch) and resource (contact attribute key), and the word 'single' implicitly distinguishes it from the sibling formbricks_list_contact_attribute_keys. It is clear but does not explicitly name or contrast with that sibling.

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: 'single' suggests this is for retrieving one key by id rather than listing, but there is no explicit when-to-use guidance, no stated prerequisite (e.g., needing a valid key_id), 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 the safety profile is covered. The description adds real value beyond that by disclosing the return payload (answers, metadata, completion state) and the underlying API route, which is useful given there is no output schema.

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

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

Two tightly packed sentences: purpose and payload first, API mapping second. No filler, nothing that could be cut without losing information.

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

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

For a simple single-argument read tool with no output schema, the description covers what the tool does and roughly what comes back. It stops short of explaining error behavior for an invalid or deleted response id, but nothing critical 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?

Only one parameter exists and schema description coverage is 100%, so the schema fully documents 'response_id'. The description adds no format, source, or example guidance beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (Fetch) and resource (a single survey response), and the word 'single' implicitly distinguishes it from the sibling list_responses. It does not name the sibling explicitly the way a 5 would, but the scope 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?

Usage is only implied: fetch one response by id. There is no explicit when-to-use statement, no alternative named (e.g. list_responses with a filter), and no stated prerequisites such as required permissions or a valid survey link. Minimum viable but with clear gaps.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description only needs to add context. It adds the raw v2 endpoint and the attribution purpose, but says nothing about auth requirements, whether the link expires or is single-use, or rate limits.

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 purpose front-loaded and the usage gloss immediately after. The raw endpoint reference is mildly redundant for an agent, but it is compact and useful for correlating with Formbricks API docs.

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 only two fully described params and no output schema, the description does its job: it identifies the return value (a survey URL) and the safety profile is carried by annotations. Remaining gaps (link lifetime, single-use behavior) are minor for a read-only lookup tool.

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

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

Schema description coverage is 100%, so both parameters are already documented and the description need not restate them. Beyond echoing the IDs inside the endpoint template, it adds no syntax, format, or lookup 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?

The description states a specific verb and resource ('Get the personalised survey URL for one contact') and explains what the artifact is for, which an agent can act on directly. It does not, however, differentiate itself from the sibling formbricks_get_survey_segment_links, which is a near-neighbour capability.

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

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

Usage is implied by the gloss 'the link you send so their response is attributed to them', which conveys the intent of attributing a single contact's response. There is no explicit when-to-use/when-not guidance and no mention of the segment-links alternative, so routing still requires inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully discloses the bulk-enumeration behavior (one URL per contact), but says nothing about pagination limits or response shape beyond that. Adequate but not rich.

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

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

One tight sentence plus the API endpoint, with the core purpose front-loaded. No filler or redundant restatement of the title.

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

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

For a read-only paginated lookup with no output schema, the description conveys what comes back (personalised URLs per contact) and the schema carries paging. Missing only return-structure hints, which is minor here.

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 survey_id, segment_id, skip and limit are already documented in the schema. The description adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (get) and resource (personalised survey URLs for a segment) with clear scope ('for every contact in a segment'). This distinguishes it from the singular sibling formbricks_get_survey_contact_link.

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 'how you run a targeted send' gives explicit usage context for when to reach for this bulk tool rather than a single-link lookup. It stops short of naming the singular sibling or stating exclusions, so not a 5.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe, non-mutating call. The description usefully adds the concrete endpoint ('Formbricks v2: GET /health'), which helps with debugging, but says nothing about what a success vs. failure response looks like. Some added value beyond annotations, but not rich.

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

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

Two short sentences with zero padding; the purpose is front-loaded and the endpoint detail follows. Nothing is wasted.

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

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

For a trivial no-argument probe with no output schema, the definition covers what the agent needs to invoke it. It could have noted the expected return (e.g., an ok/status payload) since no output schema exists, but that is a minor gap for a tool this simple.

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, and the schema coverage is 100%, so there is nothing for the description to disambiguate. Baseline 4 applies for a parameterless 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?

States a specific verb ('Check') and resource ('Formbricks API'), and the phrase 'is reachable' pins the scope to connectivity rather than data retrieval. This cleanly distinguishes it from every sibling, which all operate on contacts, responses, webhooks, surveys, or users.

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 purpose inherently implies when to use it (verifying connectivity/availability before or during other calls), but the description never states that context explicitly and names no alternatives. For a zero-parameter health probe this is adequate but leaves the trigger condition to inference.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds the underlying API route (Formbricks v2: GET /management/contact-attribute-keys), which is mildly useful context, but says nothing about pagination behavior despite the tool exposing skip/limit/order/sortBy, nor about scoping via workspaceId/environmentId.

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 tight sentence with the core purpose front-loaded, followed by a short endpoint reference. Nothing is padded, though the API route citation earns its place less than a note about paging or environment scoping would have.

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 the conceptual return content ('the schema of what you know about a contact') clearly enough to act on. The remaining gap is that return shape and pagination semantics are left entirely to the schema, which is acceptable given 100% schema coverage.

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

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

Schema description coverage is 100%, so all six parameters (skip, limit, order, sortBy, workspaceId, environmentId) are already documented in the schema. The description contributes no additional parameter meaning beyond the singular mention of 'environment', 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 (List) and resource (contact attribute keys) and adds a gloss clarifying what those keys represent — 'the schema of what you know about a contact'. The plural form implicitly distinguishes it from the sibling formbricks_get_contact_attribute_key, but the description never names that sibling explicitly, so differentiation is inferred rather than stated.

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: an agent can infer this tool is for discovering the set of attribute keys before creating/updating contacts. There is no explicit when-to-use guidance and no statement of when to prefer this over formbricks_get_contact_attribute_key, which is a genuine ambiguity given the near-identical names.

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 nature is covered. The description adds the underlying endpoint mapping (v2: GET /organizations/{organizationId}/users), which is useful orientation but not behavioral detail such as pagination semantics or permission 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; the functional purpose is front-loaded and the endpoint reference trails as useful metadata. Efficient with no filler.

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

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

For a read-only list tool with full schema coverage and no output schema to explain, the description covers purpose and scope adequately. It omits pagination behavior, but that is minor given the schema documents skip/limit fields directly.

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 five parameters are self-documented in the schema, establishing a baseline of 3. The description's mention of id/email lookup lightly reinforces two of those parameters but adds no syntax or format detail beyond the schema.

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

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

States a specific verb (List) and resource (users in an organisation), with the additional clarification that lookups can be narrowed by id or email. The purpose is immediately clear, though it doesn't explicitly differentiate from siblings like list_roles or list_teams — it relies on the resource noun to do that implicitly.

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 notes that results can optionally be narrowed by id or email, which gives some context for filtering. However, it offers no when-to-use/when-not guidance and names no alternatives, leaving usage 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 already tells the agent this is a safe read. The description adds the upstream endpoint (GET /management/responses), which is modest extra context. It omits pagination behavior and expected page-size coupling that a 9-param list tool would benefit from.

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 front-loaded sentences with the primary purpose first and the filter scope second. 'The answers people gave' is arguably filler, but it aids disambiguation at minimal cost.

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 full schema coverage, a readOnly annotation, and no output schema to explain, the description covers what an agent needs to call it. Return shape and pagination defaults are the only unaddressed items, both minor for a read tool.

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

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

Schema description coverage is 100%, so all nine parameters are already documented with types, enums and ranges. The description reinforces survey/contact/date-window filtering but adds no syntax or semantics beyond the schema; 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 ('List') and resource ('survey responses') and immediately scopes it ('optionally narrowed to one survey, one contact or a date window'). The phrase 'This is the main read: the answers people gave' implicitly separates it from the singular formbricks_get_response sibling.

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

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

Gives clear usage context ('main read' for the answers) and enumerates the three narrowing dimensions, so the agent knows when this bulk-read applies. It never explicitly names get_response or delete_response as alternatives, so it stops short of full alternative routing.

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 only the endpoint mapping (GET /roles) and that roles pertain to organisation users; it says nothing about whether the list is static, paginated, or permission-gated.

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 purpose. The second sentence ('Formbricks v2: GET /roles') is largely restated metadata that overlaps the tool name, so it earns less than full marks.

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 no output schema, the description is sufficient to call it correctly; a note on what the returned roles represent (fixed vs custom) would close the remaining gap.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly conveys that no filtering input is expected, though there is no parameter content for it to clarify.

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 (List) and resource (roles), and narrows scope to roles assignable to organisation users, which no sibling tool covers. It does not explicitly differentiate itself from siblings like formbricks_list_organization_users, but the resource is unambiguous.

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

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

Usage is only implied: an agent can infer you call this to discover role names/IDs before assigning them. There is no explicit when-to-use statement, no alternatives named, and no note that the list is a fixed catalogue versus tenant-specific data.

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, and the description only restates this implicitly via the GET endpoint reference. It adds version context (Formbricks v2) but says nothing about pagination defaults, result limits, or permission requirements beyond what the annotation and schema already 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?

Two short, front-loaded sentences with virtually no waste. The API endpoint reference is somewhat redundant with the name and annotation, but it 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?

With no output schema, the description gives no indication of the return shape, and it does not explain pagination behavior despite paginated parameters. Annotations cover the safety profile, so the remaining gap is moderate but real for a list tool.

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

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

Schema description coverage is 100%, so all five parameters (including skip, limit, order, sortBy) are already documented in the schema. The description adds no parameter semantics on top of that, which is the baseline-3 case.

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

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

States a specific verb and resource ('List the teams in an organisation'), which is enough for an agent to distinguish it from sibling list tools such as formbricks_list_organization_users and formbricks_list_roles. It is clear but does not explicitly name or contrast 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?

There is no when-to-use or when-not-to-use guidance, no mention of alternatives, and no prerequisites. The agent can only infer usage from the tool name and the required organization_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?

The readOnlyHint annotation already establishes this is a safe read. The description adds that results are scoped to survey-event webhooks and identifies the underlying endpoint (GET /management/webhooks), but says nothing about pagination defaults 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 short sentences, with the resource scope front-loaded before the endpoint reference. The API-reference clause is mildly expendable but still aids endpoint identification.

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 zero-required-parameter list tool with no output schema and full schema coverage, the description covers the essentials. It is slightly thin on what a returned webhook record contains, but not deficient for this complexity level.

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 surveyIds are already fully documented in the schema. The description only restates the surveyIds filtering behavior, adding no syntax or 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 verb (List) and resource (webhooks) plus the scope condition that they fire on survey events. It does not differentiate itself from siblings such as formbricks_get_webhook (single) or formbricks_create_webhook, though the naming makes the distinction fairly obvious.

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 'optionally filtered to specific surveys' implies when the surveyIds filter is appropriate, but there is no explicit when-to-use guidance or pointer to formbricks_get_webhook for retrieving a single webhook.

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 declares a safe read, and the description adds the concrete behavioral payload: it reveals the project and environment the key belongs to. The 'GET /me' note reinforces it is a pure read with no side effects. It stops short of noting auth-failure behavior, but adds real value 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 tightly packed clauses plus an endpoint reference, with the identity/ids payoff front-loaded. No filler or restatement of the tool title.

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

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

For a zero-param, no-output-schema tool, the description covers what is returned (project, environment) and why it matters (ids needed by other tools). The only omission is failure/auth-requirement behavior, which is minor given the readOnly annotation.

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 there is nothing for the description to disambiguate; it correctly implies the only input is the pre-configured x-api-key. Baseline 4 for a param-free 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?

States a specific verb+resource: it returns the project and environment that the configured x-api-key belongs to. Clearly distinguishable from every sibling (which act on contacts, webhooks, responses, etc.). An agent knows exactly what this tool produces.

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 frames itself as 'the fastest way to find the workspace and environment ids the other tools need,' which tells the agent when to reach for it. It does not name an alternative tool or state exclusions, but for a zero-arg identity lookup 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.