User Intuition

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the output is generated statements with numbered citations tied to canonical content IDs, plus source details and index status. It does not mention latency, cost, or what happens if the index is stale.

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

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

Three tightly packed sentences that front-load what the tool returns and end with the sibling routing. Every sentence earns its place with no filler.

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

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

An output schema exists, so the description needn't enumerate return fields, yet it still summarizes them usefully. The main shortfall is the unaddressed filter parameters and index-readiness prerequisites for a tool with a nested required object.

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

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

Schema coverage is only 33%, and the description never mentions the filters object fields (content_types, research_date_from/to) or the 20-study cap. 'Selected accessible studies' hints at the study_ids filter, but the nested filter semantics and valid content types are left entirely to the schema, so the description only marginally compensates for the coverage gap.

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

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

States a specific verb (answer), resource (question across selected studies), and mechanism (indexed research), then distinguishes itself from search_research by naming what it does differently (inspect underlying records). An agent can pick between the two 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 final sentence explicitly routes the agent to search_research for inspecting raw records, giving a clear alternative. However, it doesn't say when NOT to use this tool (e.g. no accessible studies, index not ready) or what prerequisites like an existing index imply.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so safety and repeat-call behavior are covered structurally. The description adds the state-machine constraint (cannot cancel an answered request), which is genuine extra context, but says nothing about reversibility, resulting state, or error 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?

Two short sentences, zero filler, with the core action front-loaded and the constraint immediately after. 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?

With an output schema present, the description need not explain return values, and the annotations carry the safety profile. Purpose plus the pending-only constraint is largely sufficient for a single-required-param cancel operation, though failure modes are 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 50%: organization_id is documented in-schema while request_id relies on its uuid format/pattern. The description adds no parameter meaning at all, so it neither compensates for the gap nor falls below the baseline for mid coverage.

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 and resource ('Withdraw a pending feasibility request'), which cleanly separates it from siblings like submit_feasibility_request and get_feasibility_request. It is clear without naming those alternatives explicitly, so it lands 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?

It supplies a real precondition — only pending requests can be cancelled; an answered request cannot — which tells the agent when this tool will fail. It does not, however, point the agent at alternatives such as get_feasibility_request to verify status first.

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

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

Beyond the annotations (readOnly=false, idempotent=true, openWorld=true), the description discloses that this is a create-or-replace write, that repeating an identical PUT preserves the entry token, and that human approval and provisioning verification are prerequisites to sharing entry_url. These are operational behaviors the structured hints do not convey.

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

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

Five sentences, front-loaded with purpose and followed by parameters, prerequisites, exclusions, and idempotency. Every sentence adds distinct information with no filler.

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

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

For a 13-parameter write tool with an output schema and rich annotations, the description supplies the workflow gates, the write semantics, and the idempotency nuance. Return values are covered by the output schema, so nothing an agent needs to invoke this correctly is missing.

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

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

With schema description coverage at only 8%, the description carries most of the load: it names the required redirect URLs, the respondent ID query param and placeholder, and the optional session/external-study/quota-full/technical-failure mappings. It omits the provider enum values, organization_id, and study_id semantics, which is the only real gap.

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

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

The description names a specific verb and resource ('Create or replace a customer-supplied panel bridge on an owned BYOP study') and explicitly scopes what it is not ('does not recruit respondents or launch the paid User Intuition Panel'). This cleanly separates it from siblings like launch_panel, delete_external_panel, and regenerate_external_panel_token without the agent 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?

It states both the when and the when-not plus the gating sequence: call get_study, verify provisioning_status=provisioned, and obtain human approval before sharing entry_url. The exclusion clause routes the agent away from panel-launching tools, and the 'repeating the same PUT' note tells the agent it is safe to re-issue.

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

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

Annotations only declare the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true); the description adds genuinely new behavior: creation is queued asynchronously and must be polled, invitations are sent unless silent=true, and approval validity is carried via study_id/updated_at and invalidated by changed plan or invitation settings.

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

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

Front-loads the action and its bound, then the workflow, then the approval and invitation rules. Every sentence carries information, though the approval-invalidation clause is densely packed into a single run-on sentence.

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

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

An output schema exists, so return values need not be described; instead the description supplies the operational context an agent actually needs — async job polling, hard prerequisites, approval reuse/invalidation rules, and invitation side effects — which is complete for a mutating batch-create 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 50%, and the description reinforces the batch bound ('1–100 unique') and the effect of silent. However, it says nothing about idempotency_key or organization_id, both of which are documented only in the schema, so it does not fully compensate for the coverage gap. Baseline 3 fits.

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 with scope: 'Queue creation of 1–100 unique BYOP participants.' The async framing ('Queue') and the 1–100 bound distinguish it immediately from sibling reads like get_participant and list_participants.

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

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

Gives an explicit pre-flight sequence (call get_study, require provisioning_status=provisioned, verify or obtain explicit approval of the current plan) and an explicit post-flight sequence (poll get_participant_job until succeeded, then list participants). Named siblings and the conditions that select them leave nothing to inference.

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

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

Annotations only supply the generic profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false). The description goes well beyond: it clarifies this produces a draft rather than a live study, lists the implicit defaults (voice interview, English, Elliot) applied on omission, states cross-parameter constraints (synthetic respondents require chat; prototype-tests require video or voice, never chat), and warns against a delegating model fabricating human confirmation of recruiting_method — a genuine behavioral/policy disclosure an agent could not infer elsewhere.

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

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

Purpose and the recruiting_method precondition are front-loaded, and almost every sentence carries operational content. It is nevertheless dense and slightly repetitive: the concept/prototype asset instructions restate what customize_study already owns, and the closing 'Voice configuration is kept for chat as well as voice and video' duplicates the schema's own voice description.

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

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

For an 8-parameter, open-world creation tool with an output schema present, the description covers the full workflow an agent needs: create the draft here, then hand the natural-language brief and any concept/prototype assets to customize_study, with the required asset fields enumerated per study type. Return values are correctly left to the output schema.

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

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

Schema coverage is 88%, so the schema already carries most parameter documentation (including the voice/language/format defaults). The description still adds meaning beyond the schema by supplying cross-field constraints, e.g. 'Synthetic respondents require chat' and the prototype-must-not-be-chat rule, and by framing recruiting_method as a human-confirmation requirement rather than a plain enum. It does not, however, add much on name, idempotency_key, or organization_id.

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 (Create) and resource (study) and enumerates the three supported study modes, then states the boundary: 'using ordinary metadata only' and 'Do not draft or pass the study plan, audience targeting, screener questions... here.' It distinguishes itself from the nearest sibling by routing brief customization to customize_study, so an agent can pick between the two without opening schemas.

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

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

Gives explicit when-to-use rules per study type ('For a concept test... For a prototype test...'), an explicit alternative (customize_study for the research brief, concept images, prototype assets), and hard preconditions (recruiting_method must be an explicit human choice). It also names the exceptions ('Unless the human requests otherwise').

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false). Beyond that, the description adds a genuinely non-obvious behavioral trait: the signing secret is returned only once and must be stored securely. That is valuable context the annotations cannot convey, though permissions and idempotency of duplicates are unaddressed.

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 scope, event choices, and the one-time secret caveat each earn their place.

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

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

With an output schema present, return value detail is not needed, and the description sensibly covers the one thing the output schema cannot guarantee the agent notices (the one-time secret). Only minor gaps remain around duplicate-webhook behavior and permission requirements.

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 only 25%, so the description must carry weight; it does enumerate the three valid event values and clarifies that study_id is optional (account-level vs one owned study). It does not explain that hook_url must be a reachable URI endpoint or clarify the role of organization_id, so compensation is partial.

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 ('Create a webhook') and clarifies the two ownership scopes (account-level or a single study), which tells an agent what the tool produces. It does not explicitly differentiate itself from the sibling create/delete/rotate webhook tools, but 'create' 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?

The description implies when to use it by listing the selectable event types and the account-vs-study scope, and warns the secret is shown once. It never states prerequisites, when NOT to use it, or how it relates to siblings like test_webhook or rotate_webhook_secret, so usage guidance 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?

Annotations only supply generic hints (readOnlyHint=false, openWorldHint=true, idempotentHint=false). The description adds substantial context beyond them: 'This call never starts recruitment,' plans and setting changes are persisted, task durability for 2026 clients, and the idempotency/timeout behavior for reuse.

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

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

The core action is front-loaded and every sentence conveys distinct guidance. It is dense and long, with several branching instructions packed together, but little is pure 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?

An output schema exists so return values need not be explained, and the description covers the multi-step workflow, persistence, mode selection, and approval gating an agent needs to invoke it correctly.

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

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

Schema coverage is 86%, so the schema carries most parameter docs (baseline 3). The description still adds real meaning: execution_policy holds workflow constraints 'never in message,' decisions=agent vs human semantics, and the concept_image labeling/base64-encoding guidance.

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 action ('Send one research-design turn to Customize Plan') that clearly separates it from siblings like queue_customize_study and get_customize_study_job. The phrasing is somewhat jargon-heavy ('research-design turn', 'Customize Plan'), but the verb+resource is identifiable.

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

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

It explicitly routes between modes: async task + poll tasks/get when no concept_image, synchronous call for native concept images, decisions=agent only when the human delegated choices, otherwise human mode. It also names downstream steps (get_study, approval before invitations/paid launch) and the execution_policy alternative for constraints.

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

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

Goes well beyond the annotations: it discloses the soft-disable effect (existing interviews remain), the operational consequence (provider can no longer send new respondents), and the repeat-call behavior (404), which aligns with and enriches idempotentHint=false and destructiveHint=true.

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

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

Three short sentences, front-loaded with the action and effect, then the side effect, then the error case. 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?

With an output schema present, return values need not be explained, and the description covers action, side effects, and error behavior. What it omits is auth/ownership specifics and how the optional organization_id changes behavior.

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

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

Schema coverage is only 50% – study_id has no description in the schema or here, and organization_id is documented only in the schema. The description's 'owned BYOP study' hints at ownership requirements but adds no parameter-level detail to compensate for the gap.

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

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

States a specific verb and resource (disable the external-panel entry link) and immediately scopes it to an 'owned BYOP study.' The clarifying verb 'disable' plus the note that interviews remain cleanly separates it from sibling delete_* tools that remove data.

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?

Implies the context (owned BYOP study with an external panel link) but never states when to choose this over configure_external_panel or regenerate_external_panel_token, nor any prerequisites or exclusions. Usage is inferable rather than explicit.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds meaningful context beyond them: the deletion is 'soft' (data not hard-destroyed) and restricted to interviews the caller owns, plus a human-confirmation guardrail. It omits any permission/error behavior and how soft-deleted records behave in later reads.

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 action and followed by the invocation guard. Every clause earns its place with no filler.

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

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

An output schema exists so return values need no explanation, and annotations carry the safety profile. The description covers purpose, soft-delete semantics and the human-approval gate, but leaves the admin-only organization_id path unaddressed, which is the one notable gap for a 2-parameter delete 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 50%: interview_id is self-evident and organization_id carries its own note about platform-admin org selection. The description adds only the ownership scoping implication and never mentions organization_id or the admin-only organizational context, so it does not compensate for the coverage gap. 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 ('Soft-delete an interview') plus an ownership scope ('owned by the authenticated user'), which cleanly separates it from the delete_participant/delete_study/delete_webhook siblings. It stops short of naming an alternative tool, so it is clear but not sibling-routing.

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

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

Gives an explicit gate: 'Call only when the human explicitly requests deletion of this interview,' which tells the agent when to act and implicitly when not to. It does not name alternative tools (e.g., get_interview or list_interviews) for adjacent needs, so it falls short of a full when/when-not/alternatives treatment.

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

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

Goes well beyond the annotations: it discloses that deletion is a soft-delete, that the personal link is removed as a side effect, that existing interviews cause a conflict response, and that cascade requires separate user approval. The destructive/idempotent/openWorld hints are already covered by annotations, and this adds meaningful operational detail on top.

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

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

Three tight sentences, front-loaded with the action and scope, then side effects, then the failure/approval condition. No sentence is redundant and nothing important is buried.

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

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

An output schema exists, so return values need no explanation, and the description covers the mutation semantics, side effects, and conflict resolution path. The only mild gap is what 'soft-delete' means for recoverability or subsequent state of the participant record.

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 only 33%, so the description must compensate, and it does for the undocumented cascade_interviews by explaining exactly when the flag is needed and why. participant_id is self-explanatory from its UUID format, and organization_id is already documented in the schema, leaving no real gap.

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

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

States a specific verb and resource with scope ('soft-delete one BYOP invitation'), which is precise enough to distinguish it from delete_interview and delete_study in the sibling list. It does not, however, explicitly name a sibling alternative, 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?

Gives a clear usage condition ('after the user explicitly requests it') and spells out the conflict path when interviews exist, including the condition (user approval + cascade_interviews=true) that resolves it. It stops short of naming when to use delete_interview instead, so it is clear context without explicit alternatives.

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

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

Goes well beyond the destructiveHint/idempotentHint annotations: it discloses that this is a soft-delete affecting normal reads, that participant links break, that there is no public restore endpoint, and that uploaded assets may have separate retention. These are exactly the consequences an agent needs before calling a destructive tool.

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

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

Four tight sentences, front-loaded with the most consequential fact (soft-delete + cascade), then consequences, then the authorization precondition. Nothing is filler.

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

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

For a destructive, cascading operation the description covers reversibility, side effects, and the human-approval requirement; an output schema exists so return values need not be explained 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 50% (organization_id is documented in the schema; study_id is not). The description adds no parameter-level meaning at all, so it does not compensate for the undocumented study_id.

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 (soft-delete) and resource (study) plus the cascade scope: linked invitations, interviews, and reports. An agent can distinguish this from delete_interview or delete_participant because the cascade is named 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?

Gives a hard precondition: 'Call only when the human explicitly requests deletion of this study.' That is an unusually strong when-to-use signal, though it does not name alternatives such as stop_study or pause_study for the non-destructive case.

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

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

Annotations already declare destructive=true, idempotent=false, openWorld=true, so the safety profile is covered. The description adds real behavioral context beyond that: the deprecation status, why the alternative exists, and the concrete failure mode that a repeated deletion returns 404.

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

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

Three short sentences, front-loaded with the deprecation status, then the replacement path, then the error behavior. No filler; each sentence carries information.

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

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

An output schema exists so return values need no explanation, yet the description still flags the 404-on-repeat behavior that matters for a non-idempotent destructive call. The main residual gap is the undocumented hook_url parameter, which the schema also leaves bare.

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

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

Schema description coverage is 50%: organization_id is documented in the schema, but hook_url carries no description anywhere. The description only hints that the hook URL can be obtained by listing webhooks, which gives partial semantics without adding format or matching details.

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 establishes this as a deprecated deletion path and names the operation indirectly through the sibling it defers to (delete_webhook_by_id). The verb+resource is implied by the name/title rather than restated, but an agent can distinguish it from create_webhook, get_webhook, and delete_webhook_by_id.

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

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

It gives an explicit sequence ('List webhooks, then use delete_webhook_by_id') and the condition that selects the alternative: clients that omit DELETE request bodies. It does not state affirmatively when this legacy tool is still the right call, so it stops short of a full when/when-not pairing.

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, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds real value on top by disclosing the repeat-call failure mode ('A repeated deletion returns 404'), which tells the agent this is not a safe retry. It stops short of saying whether queued deliveries or the signing secret are affected.

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, effect first, edge-case behavior second. Nothing is wasted and the important part is front-loaded.

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

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

An output schema exists and annotations carry the mutation profile, so the description need not explain returns. For a simple by-id delete it covers the essentials, though it omits the platform-admin organization_id scoping caveat that the sibling mutation tools share.

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 50%: organization_id is documented in the schema, but webhook_id carries no description at all. The description says 'one registered webhook' but adds no format, lookup, or requiredness detail, so it fails to compensate for the uncovered required parameter.

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 effect ('Stop future deliveries') on a specific resource ('one registered webhook'), which is more informative than a bare 'delete'. However, it does not distinguish itself from the sibling delete_webhook, leaving the agent to guess which of the two deletion tools applies.

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

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

No when-to-use guidance, no prerequisites, and no mention of the obvious alternative delete_webhook or of rotate_webhook_secret for less destructive changes. The agent gets no routing signal.

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, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely non-structured context: that the price and balance can change before launch, and that an explicit approval step precedes any paid launch. It also lists the returned fields, which is partly redundant given the output schema exists.

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

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

Three tight sentences, front-loaded with the core purpose, followed by the approval gate and the routing rule. The enumeration of return fields (cost, balance, deficit, reward, card hold, recurrence, timeline) is the only slightly padded element since an output schema exists.

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 estimation tool with 6 params, an output schema and rich annotations, the description covers purpose, the approval workflow, staleness caveat, and the sibling-routing rule. An agent has everything needed to call it and interpret the result correctly.

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

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

Schema coverage is only 50%, but the description supplies the key semantic threshold for incident_rate (<10 routes elsewhere) and the practical ceiling tying to target's 1000 maximum. Country-code provenance is already documented in the schema, so the description sensibly doesn't repeat it.

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

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

States a specific verb and resource plus scope: 'Read-only estimate for one Panel recruitment cycle.' This clearly separates it from launch_panel (which spends money) and submit_feasibility_request (which handles edge cases), so an agent can route 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?

Names the explicit workflow gate ('Ask for explicit approval of the estimate before any paid launch') and the alternative with its triggering condition ('use submit_feasibility_request for incidence below 10% or more than 1,000 interviews'). Both when-to-use and when-to-use-something-else are present.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, but not the async lifecycle. The description usefully adds that the operation queues work and returns either a durable task or a job ID depending on client type, plus the webhook completion signal. This is meaningful behavioral context beyond the structured fields.

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

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

It is short and front-loaded with the queueing action, but the sentence 'Then call get_study_report. report.ready webhooks also signal completion.' is garbled and reads as two fragments. The content is dense but the structure is choppy.

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

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

An output schema exists, so return values needn't be described, and the async polling path is covered. However, for an async, non-idempotent queueing tool, key gaps remain: what 'analysis' is produced, permissions/auth needs, and any meaning for study_id 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 67%, so the schema already documents idempotency_key and organization_id, but study_id is undocumented. The description adds no parameter meaning at all, so it neither compensates for the gap nor expands on the covered params. Baseline 3 is appropriate.

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

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

The description opens with 'Queue analysis,' which describes an action but never states the core verb+resource (generating a study report) that the title and sibling tools imply. An agent must infer the actual purpose from 'get_study_report' and 'report.ready'. It is adequate but the primary purpose is only implied.

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 lays out the polling workflow after queueing (durable task vs job ID, then get_study_report), which is contextual usage guidance. However, it gives no when-to-use vs alternative guidance, no prerequisites, and no exclusions relative to siblings like get_report_job or get_study_report.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely non-obvious behavioral meaning: a payment method on file does not constitute spending approval, and human approval must be obtained using the current estimate. It does not discuss auth scoping (the platform-admin-only constraint lives in the schema) or rate/refresh characteristics.

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

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

Two sentences, zero filler, with the primary purpose front-loaded and the spending-approval caveat immediately after. Every clause earns its place.

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

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

For a read-only account/readiness check with a 1-param schema and an output schema, the description covers purpose, trigger, and the key operational caveat, so an agent can call it correctly. The only gap is that it never clarifies its relationship to sibling read tools such as list_organizations.

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 optional organization_id is already documented as a platform-admin-only scoping parameter. The description adds no syntax or behavioral detail about when to pass it, so the baseline 3 for a schema-documented parameter applies.

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

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

The description opens with a precise verb ('Read') and an enumerated resource set (effective workspace, role, credit balance, payment method readiness, incentive limits), so the agent knows exactly what comes back. It does not name or compare against any sibling (e.g. list_organizations), so the differentiation is implied 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?

It gives a clear situational trigger: call this 'before a paid action', which tells the agent when the tool belongs in a workflow. It stops short of naming alternatives or exclusions (e.g. when list_organizations is preferable), so it is a strong context statement rather than full when/when-not 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 establish readOnlyHint=true, idempotentHint=true and non-destructive, so the safety profile is covered. The description adds real context beyond that by defining this as a poll and by naming the terminal states ('succeeded', 'failed') and their handling. It omits intermediate states and polling cadence, which keeps it from a 5.

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

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

Three short sentences, no filler, and the core action ('Poll...') is front-loaded. Each sentence adds a distinct operational instruction.

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

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

An output schema exists, so return values need not be described, and the description covers the two terminal branches well. It is slightly incomplete for a polling tool because it doesn't mention in-progress/pending states or how long to wait before re-polling.

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 only 33%. study_id and job_id carry no descriptive text, and the description never explains what the job identifier represents or how it is obtained (presumably from queue_customize_study). Only organization_id has schema documentation, so the description leaves most parameters unexplained.

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: 'Poll a queued study customization turn.' The polling role is clear and implies it pairs with queue_customize_study. It does not explicitly name sibling alternatives, so an agent must infer the workflow boundary, but the purpose itself 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?

Gives outcome-based instructions: on succeeded call get_study, on failed inspect the saved study before retrying. This is concrete workflow guidance with named next steps. It does not address when polling is unnecessary or distinguish this from get_participant_job/get_report_job, so it stops short of the top tier.

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, idempotentHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds the useful ownership constraint ('one owned BYOP study') and specifies what content is returned, but says nothing about auth requirements, rate limits, or behavior when the study has no external panel configured.

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 read action and scope front-loaded, followed by the disambiguation clause. No filler, though the second sentence's distinction could be slightly tighter.

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 an output schema present, return values need not be explained, and the description covers purpose, scope, and differentiation adequately for a 2-parameter read tool. The only gap is the undocumented required study_id parameter and lack of any error/edge-case note.

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 only 50%: organization_id is documented as platform-admin-only, but study_id carries no description in either schema or description text. The description adds no parameter-level meaning (e.g., what counts as an owned study, UUID format expectations), so it does not compensate for the coverage gap.

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

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

The description names a specific verb (Read) and resource (customer-supplied panel entry link, respondent ID parameters, outcome redirects) scoped to one owned BYOP study. It explicitly differentiates from sibling tools configure_external_panel/delete_external_panel and from separate concepts (individual BYOP invitations, paid Panel recruitment), so an agent can identify it 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?

It clearly states the disambiguation context ('This is distinct from individual BYOP invitations and paid User Intuition Panel recruitment'), which helps an agent route correctly. However, it stops short of naming the directly competing siblings (configure_external_panel, delete_external_panel, regenerate_external_panel_token) or stating the read-vs-write selection condition explicitly.

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, idempotentHint, destructiveHint=false, and openWorldHint, covering the safety profile. The description's only added behavioral note is that the result carries 'status or estimate', which is largely redundant with the existing output schema; it says nothing about failure modes like an unknown request_id.

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 verb and resource front-loaded and no filler. Nothing could be trimmed without losing meaning.

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 single-record fetch with an output schema handling return values and annotations covering safety, the description is close to sufficient, merely noting the status/estimate content. It omits any error or not-found behavior, which is a minor gap.

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

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

With schema description coverage at only 50%, the description should compensate for the undocumented request_id, but it adds no parameter meaning at all. The one non-obvious parameter (organization_id, with its admin-only restriction) is explained solely by the schema text.

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

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

States a specific verb ('Get'), resource ('feasibility request'), and scope ('one'), which implicitly separates it from the plural list_feasibility_requests sibling. It never names that sibling or any other tool, so the differentiation is inferable rather than explicit.

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 mention of when to prefer this over list_feasibility_requests or submit_feasibility_request, and no stated prerequisites (e.g., needing an existing request_id). The retrieval-by-id usage is only implied by the schema's required request_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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by explaining what metrics are returned (completions vs target, quality counts, expected finish) and the condition 'when enough progress exists' signals a possible partial result. However, it doesn't detail auth requirements or rate limits beyond the organization_id note in 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?

The description is a single efficient sentence that front-loads the key returned content. It avoids redundancy and is appropriately sized for a read-only tool.

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

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

Given the tool has an output schema, the description needn't detail return values. It covers the core purpose and a conditional behavior, and annotations cover safety. The only gap is lack of explicit usage context in a dense sibling set, but overall it is nearly complete for an agent to invoke correctly.

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

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

Schema coverage is 50%; the organization_id parameter is well-documented in the schema itself, and study_id is required with format constraints. The description adds no parameter-level semantics. With one parameter documented and one lacking a description, baseline 3 is appropriate as the schema does the heavy lifting for the documented parameter, but the description could clarify organization_id scoping.

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 clearly states the specific resource and content: qualifying completions vs target, quality counts, and a rate-based expected finish. This distinguishes it from siblings like get_study or get_interview_usage_stats. However, it doesn't explicitly differentiate from other study-related progress tools, leaving slight ambiguity in a large sibling set.

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 'when enough progress exists' implies a usage condition, but no explicit when-to-use vs alternatives is provided. In a sibling set with many study tools, an agent would have to infer that this is for monitoring fielding progress, not for pausing, stopping, or configuring studies.

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, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: a ~20 KB text bound, a 100-segment cap, and the guarantee that system prompts and internal metadata are excluded while turn IDs and text_offsets are preserved.

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 dense sentences that front-load the returned payload before pagination guidance. Efficient overall, though the incorrect parameter name in the second sentence costs a point.

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

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

An output schema exists, so return-value shape need not be re-explained, and the description still covers the key operational facts an agent needs: content bounds, pagination, and what is filtered out. The only gap is the misnamed pagination parameter and no guidance on sibling selection.

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 only 25%, so the description is expected to compensate. It hints at the limit and pagination but references 'next_message_offset', which is not a real parameter (the schema uses message_offset) — a naming error that actively misleads. organization_id is documented only in the schema.

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

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

States a specific verb (get) and resource (interview), then enumerates exactly what comes back: timing, stored format, study language, and spoken transcript segments. That enumeration clearly distinguishes it from siblings like list_interviews and get_interview_usage_stats.

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 real usage guidance for pagination ('Use next_message_offset to fetch the next page'), which is more than most definitions offer. However, it never states when to prefer this over list_interviews or get_interview_usage_stats, and the pagination pointer names a field that does not exist in the schema.

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

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

Annotations already declare the safe read-only/idempotent profile, and the description adds real value beyond them: the non-test eligibility filter, the 30-day UTC default when dates are omitted, the backend-resolved default app, and that the applied scope is echoed back. It stops short of noting pagination or billing/eligibility edge cases.

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

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

Three tight sentences, front-loaded with the aggregation semantics followed by defaults and response scope. Each sentence carries information; no filler or restatement of the title.

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

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

With annotations covering safety, an output schema covering return shape, and 80% param coverage, the description supplies the missing operational context (defaults, filtering, echoed scope). Only cadence semantics and multi-app/multi-org behavior are 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 coverage is 80%, so the schema largely documents the five parameters itself. The description adds the default-resolution behavior for date range and app scope, but says nothing about the cadence enum values or how start/end dates interact.

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 (Aggregate) and resource (eligible non-test interview counts and billed units) scoped to a date range, so the agent knows exactly what is produced. It does not explicitly contrast itself with any sibling (e.g. get_fielding_progress or get_report_job), which keeps it short of a 5.

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

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

There is no when-to-use or when-not-to-use guidance and no named alternative among the many reporting-adjacent siblings (get_fielding_progress, get_report_job, generate_report). The mention of backend default resolution is behavioral detail, not usage 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 this is a safe, idempotent read, so the bar is lower. The description adds useful behavioral scope by saying panel respondents are not returned and by positioning the read as a verification step before mutations.

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

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

Three sentences, each earning its place: purpose and returned fields first, usage guidance second, and the panel exclusion third. No wasted wording.

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 an output schema present, the description need not document return values in detail. Annotations cover safety characteristics, and the description adds enough purpose, usage, and scope context for a simple read-one 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 only 50%: organization_id is documented in the schema, but participant_id has no description. The tool description does not explain either parameter or add semantic 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 (Read) and resource (one BYOP invitation), lists the returned fields, and distinguishes the tool from list-style siblings by saying it reads one. The explicit note that panel respondents are not returned further sharpens scope.

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 when-to-use guidance: verify the participant before changing their email, deleting the invitation, or sending a reward. It also states an exclusion for panel respondents, though it does not explicitly name an alternative tool for that case.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The word "Poll" usefully implies an async job that must be re-checked, but the description never says what states are possible, whether it can still be running, or how completion is signaled.

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, clearly front-loaded with the action and then the follow-up. Nothing is wasted, though the terseness is partly responsible for the documentation gaps noted elsewhere.

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

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

An output schema exists, so return values need not be described. But for an async polling tool the description should convey job lifecycle (pending/running/done), polling cadence, and where job_id comes from; none of that is present, so an agent cannot fully use it without guessing.

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 50%: organization_id is documented in the schema, but job_id (the required parameter) has no description anywhere. The description adds no meaning about what job_id refers to, where it comes from, or the admin-only semantics of organization_id, leaving the required parameter's origin to inference.

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 says "Poll a participant batch," which conveys that this retrieves status for an asynchronous batch-creation job, and the name reinforces it. However, "participant batch" is vague and it never explicitly says this returns job status/progress, nor does it distinguish itself from siblings like get_participant or get_report_job.

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

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

It gives one concrete chaining instruction (on success call list_participants to get invitations), which is genuinely useful workflow context. But it omits when to call it at all, how often to poll, or how it relates to create_participants versus other job-status siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds that this is an asynchronous poll and that a succeeded job yields result_url, which is useful behavioral context, but it omits terminal/error states and polling cadence.

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

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

Two short sentences with zero filler; the core action is front-loaded and the follow-up pointer is second. 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?

An output schema exists, so return values need not be spelled out, yet the description still references result_url. For a 3-parameter tool with 33% schema coverage and no annotation of failure modes, the description is adequate but leaves the job-status lifecycle and two undocumented parameters unexplained.

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 only 33% (job_id and study_id carry no description beyond uuid format), and the description adds nothing about any parameter's meaning, format, or constraints. With low coverage the description should compensate and does not.

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

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

The description names a specific verb (poll) and resource (asynchronous report request), and explicitly distinguishes this tool from get_study_report by naming it as the follow-up step. An agent can tell it apart from generate_report/get_study_report without opening any schema.

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

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

It clearly places the tool in a workflow: poll a job, and once the job has succeeded, use get_study_report to retrieve the result. The usage context is explicit, though it does not state what to do on a failed/pending job or how frequently to poll.

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

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

Annotations cover only the read/idempotency profile, while the description adds substantial behavioral context: what the payload contains, the approval workflow keyed on study_id + updated_at, the semantics of dashboard_url vs study_link, and that study_link starts the live participant experience and no researcher-preview URL exists.

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

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

Front-loads the purpose before pivoting to workflow and link semantics, and every sentence carries operational weight. It is dense and long, but not padded with redundant restatement of 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 tool with an output schema and full annotation coverage, the description supplies the workflow and return-value semantics an agent needs to act on the result (approval handling, link usage). Nothing material is missing.

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

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

Schema coverage is 50% and organization_id is already documented in the schema as admin-only. The description references retaining study_id but adds no format, scope, or usage detail beyond what the schema provides, 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 ('Get the full persisted study') and enumerates the content returned (plan, audience targeting, screeners, concept assets). The mention that these are 'managed by customize_study' cleanly distinguishes it from that sibling mutation tool.

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

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

Gives explicit triggers: call before metadata updates and after customization, and obtain approval before paid Panel launch or BYOP participant creation. It does not name read-side alternatives (e.g. list_studies or get_study_report), 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real behavioral context beyond that: the default is a small overview, and included_sections lets a caller distinguish omitted from empty sections, plus findings include structured prevalence and source quotes when available.

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 dense sentences with zero filler, and the default behavior is front-loaded before the enumeration of options. The trailing sentence about findings quotes is a useful but slightly tacked-on 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?

An output schema exists, so return values need not be spelled out, and the description still adds the response-composition nuance (overview vs section vs full, omitted vs empty). Nothing critical for a correct read-only call 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?

With only 33% schema description coverage, the description must compensate, and it does for the most consequential parameter: it explains view's default ('overview'), the section-selection semantics, and the 'full' aggregate mode. organization_id and study_id are left to the schema, but they are largely self-explanatory or already documented.

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 ('Get a small report overview by default') and enumerates the section names the view parameter can select. It is clearly distinguishable from write-oriented siblings like generate_report, but it does not explicitly name which sibling to use for a different report need.

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 context: default returns a small overview, set view to one section, or use full when all data is needed. It stops short of naming alternatives (e.g. get_report_job vs generate_report) or stating when not to use this 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description nonetheless adds a genuine behavioral fact beyond annotations: the signing secret is deliberately redacted from the response, which matters for downstream handling.

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

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

A single, front-loaded sentence with no filler; every clause carries information (verb, resource, key constraint).

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

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

An output schema exists, so return values need not be explained, and annotations cover safety. However, the description omits when to use this versus list_webhooks and says nothing about the organization_id parameter, leaving gaps for an agent calling the 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 coverage is 50%, with webhook_id required but undocumented in the schema while organization_id carries a description. The description only implies the ID lookup and adds nothing about organization_id's admin-only semantics. Baseline 3 is appropriate given the partial coverage.

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 ('Get a webhook by ID') so the agent knows exactly what it does. It implicitly contrasts with sibling list_webhooks, but does not name or differentiate against other webhook siblings such as get_external_panel or list_webhook_deliveries.

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

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

No when-to-use guidance, no prerequisites, and no alternatives such as list_webhooks for discovering an ID. The only usage signal is the word 'ID', leaving the agent to infer everything else.

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

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

Annotations declare destructive/non-idempotent/openWorld, and the description adds substantial context beyond them: backend rejection conditions (expired estimate, changed study, inputs, balance, price), the required dual approval, and the one-country-per-launch constraint. It also implies the launch is irreversible paid spend.

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

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

Front-loaded with the action and its prerequisite, then failure modes, then the escalation rule. Dense but each sentence carries operational weight; slightly long but 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?

An output schema exists so return values need no explanation; the description covers prerequisites, rejection conditions, single-country constraint, and the sibling escalation path. Complete for a destructive, paid 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 coverage is 63%, and the description reinforces the semantics of the highest-risk params (estimate_id recency/invalidation, explicit country_code, incident_rate threshold). It adds reasoning beyond the field descriptions, though frequency and organization_id are left to the schema.

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

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

States a specific verb (Launch) and resource (paid recruitment for an existing Panel study), and ties the required estimate_id back to the estimate_panel sibling so the agent knows the prerequisite flow. Clearly distinguishable from create_study and submit_feasibility_request.

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 names the escalation alternative and its trigger: 'Below 10% incidence or over 1,000 interviews, use submit_feasibility_request.' Also states prerequisite approvals for the plan and the resolved estimate before launch.

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, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description does add the useful behavioral facts of newest-first ordering and bounded (paginated) results, but says nothing about page size ceiling behavior or empty results.

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 resource and ordering front-loaded and no filler. It is efficient, though its brevity is partly under-specification rather than pure conciseness.

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

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

With an output schema present, return values need not be explained, and annotations carry the safety profile. Still, for a paginated list with an admin-scoped filter, the description leaves the paging contract and the relationship to sibling feasibility tools 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 coverage is only 33% – only organization_id is described. The description mentions 'bounded pages' but does not explain page/page_size semantics, defaults (1 and 20), or the 100-item cap, and adds nothing about the admin-only organization_id scoping beyond what the schema says.

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 (feasibility requests) scoped to the account, and adds ordering (newest first). It is distinguishable from get_feasibility_request and submit/cancel by name, though it never explicitly contrasts 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 guidance: nothing says when to page through this list versus fetching a single request via get_feasibility_request, or how it relates to submit/cancel. Usage is only implied by the verb 'List'.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds a real behavioral detail — that rows are lightweight and omit messages/recordings/screener responses — but says nothing about pagination or the cost/scale of the operation.

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

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

Two short sentences with zero filler, and the payload-shape constraint is front-loaded before the routing hint. 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?

An output schema exists, so return-value explanation is not required, and the description correctly frames the lightweight nature of the rows. However, with seven mostly-undocumented parameters and a filter-heavy list tool, the definition is thin on how to narrow results.

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 only 14% (6 of 7 params undocumented), so the description carries the burden of explaining filters and adds nothing. Status, quality, study_id, participant_id, page and page_size are never mentioned, leaving an agent to infer filter semantics entirely from 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 ('interviews') and qualifies the payload as 'lightweight interview rows', which immediately distinguishes it from get_interview. The sibling is referenced obliquely ('Fetch an interview') rather than by name, so the routing is clear but not explicit.

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 clear alternative condition: use the fetch path when you need messages, recordings, and screener responses, otherwise list. It doesn't mention any of the available filters (status, quality, study_id, participant_id), but the when-to-use-vs-alternative guidance is directly stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world. The description adds critical context beyond annotations: the permission tier required (platform admins only) and the explicit exclusion of ordinary owners/admins. It doesn't cover pagination or rate limits, but the permission model disclosure is substantive for a read 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?

Four compact sentences with zero filler. The critical access restriction is front-loaded, and the workflow instruction follows logically. Every sentence adds value.

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

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

Despite having an output schema, the description adds the critical missing piece: who can call this and how the returned organization_id feeds subsequent tools. The only gap is that page/page_size behavior (pagination semantics) is not mentioned, which matters for a list endpoint.

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

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

Schema coverage is only 50% – page and page_size are undocumented in the schema. The description compensates by explaining the search dimension (organization name, active owner name, owner email) and the downstream use of organization_id. It does not explain page/page_size, keeping this from a 5.

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

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

States a specific verb (list/search) and resource (organizations), and distinguishes itself from the many other list_* siblings by describing the search-by-owner capability. An agent can tell it apart from list_studies, list_participants, etc.

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

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

Provides explicit access gating ('Platform admins only'), describes the workflow ('Ask the human which match to use, then supply organization_id on another tool'), and states who CANNOT use it ('Ordinary organization owners and admins cannot use this tool'). This is unusually thorough routing 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: what each row represents, that panel/open-link respondents are anonymous, and that rows are participations rather than people. It omits pagination/result-shape behavior, but the output schema carries that.

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

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

Three tight sentences, front-loaded with the core action and grain definition, each carrying distinct information. No restatement of the title or 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?

The output schema and annotations cover return values and safety, and the description handles record semantics well, so an agent knows what it is looking at. However, with 6 parameters and only 33% schema coverage, the definition gives no guidance on how to filter or paginate, leaving a real gap for a list endpoint.

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 only 33% (email, study_id, page and page_size have no descriptions), so the description must compensate and does not. It never mentions filtering by email or study_id, nor the page/page_size pagination parameters, leaving most inputs undocumented anywhere.

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

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

The description names a specific verb and resource ('List BYOP invitation records') and enumerates the returned fields ('personal interview link, status and visible interview count'). It also disambiguates the overloaded term 'participant' against siblings like list_interviews and get_participant, so an agent can tell it apart 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?

It explicitly routes one case to an alternative: 'use list_interviews(participant_id) for the sessions.' It also clarifies the record grain ('study participations, not deduplicated people'), which prevents misuse. It stops short of stating when to use this tool versus get_participant or the filter conditions (email/study_id), so it is clear context without full when/when-not coverage.

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

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

With annotations already declaring readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, the description adds useful behavioral context: the sort order (updated_at descending then ID), the instruction to filter before pagination, and the meaning of interview_count (completed visible non-test interviews). It does not cover rate limits or authentication, but with strong annotation coverage this is largely sufficient.

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

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

The description is three tight sentences with no wasted words. It front-loads the core action and sorting, then adds filtering behavior, and finally clarifies a key output field and points to the alternative tool.

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

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

Given 8 optional parameters, rich annotations, and an existing output schema, the description covers the essential behaviors (lightweight listing, sorting, filtering, interview_count semantics, and the get_study alternative). It is slightly incomplete in not explaining the name parameter, but overall it provides enough context for correct invocation.

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

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

Schema description coverage is only 13%, so the description must compensate, and it partially does by mapping four filter categories to parameters (provisioning status → status, recruiting method → recruiting_method, creation date → created_after, report availability → has_report). However, it omits any mention of name, page, and page_size, leaving three parameters undocumented beyond their schema types.

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 (List) and resource (lightweight studies), including the ordering (updated_at descending then ID). It also distinguishes this tool from get_study by indicating that this returns lightweight data and directing users to get_study for the full plan, screeners, and targeting.

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 explicitly names the alternative tool (get_study) and the condition under which to use it (when you need the full plan, screeners, and targeting). It also notes that filtering should happen before pagination, giving clear operational 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds a useful caveat that age bands can be approximate, but its sentence about resolving labels refers to the full study response rather than this tool's output, which is tangential and slightly confusing about what this call returns.

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

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

Three short sentences, purpose first, usage second, caveat last; nothing is bloated. The final sentence is somewhat tangential since it concerns study responses rather than this list call.

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

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

An output schema exists, so return values need no explanation, and annotations cover the read-only safety profile. The main residual gap is filtering behavior (pagination, exact vs partial match) for a search-style tool with three parameters.

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

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

Schema coverage is only 33%: name and category have no descriptions, and the description partially compensates by implying both are search filters. It does not say whether matching is exact or substring, how the two filters combine, or how they interact with organization_id, so the compensation is incomplete.

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 ('Search the panel targeting catalog') and scopes it to name or category filters. No sibling tool covers targeting attributes, so additional differentiation isn't needed, but the name/list vs description/search wording is slightly loose.

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

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

'Use its qualification and option IDs when configuring a panel study' explains why an agent would call it and what to do with the result, which is useful context. However, it never states when NOT to use it or points to any alternative (e.g., against search_research), so usage is implied rather than explicit.

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, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds useful behavioral context: 'bounded' signals pagination, 'without payloads' sets expectations about returned data volume, and 'coarse failure reasons' indicates the granularity of failure information. It does not, however, describe pagination mechanics or any auth/permission requirements beyond what annotations imply.

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

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

The description is a single, front-loaded sentence with no wasted words. However, for a tool with four parameters and low schema coverage, the extreme brevity borders on under-specification rather than optimal conciseness.

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

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

The tool has an output schema, so the description need not explain return values; it does, however, usefully summarize the returned data ('status codes, coarse failure reasons, without payloads'). Annotations cover the safety profile. The remaining gap is the lack of any parameter guidance or usage context, which is a notable omission given only 25% schema description 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 only 25% (only organization_id is described in the schema), so the description must compensate. It does not mention any parameter by name or explain how webhook_id, page, page_size, or organization_id affect the operation. The word 'bounded' vaguely hints at pagination but adds no concrete semantic detail beyond what the schema already provides via types and defaults.

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 ('delivery attempts, status codes, and coarse failure reasons'), clearly distinguishing this from list_webhooks by focusing on delivery attempts rather than webhook definitions. The scope constraint 'without payloads' further sharpens the purpose. It stops short of naming a sibling alternative explicitly, so a 5 is not warranted.

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 is provided on when to use this tool versus alternatives like list_webhooks, get_webhook, or test_webhook. There are no prerequisites or exclusion conditions mentioned. The agent must infer usage from the purpose alone.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so safety and idempotency are covered. The description adds valuable context beyond annotations: it notes that signing secrets are never included, which is important for security and data handling. It also clarifies that study scopes are returned. This goes beyond what annotations provide, though it doesn't discuss pagination 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 concise sentences that are front-loaded with the main action and a critical detail. Every word earns its place, with no redundancy or 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 list operation with a single optional parameter, an output schema, and rich annotations, the description is nearly complete. It covers the scope of results and an important exclusion (signing secrets). However, it could mention whether results are paginated or filtered by default, which might be relevant given the openWorldHint.

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

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

Schema coverage is 100%, and the single parameter (organization_id) is fully documented in the schema with details about platform admins and required conditions. The description adds no parameter-specific information, which is acceptable given the high schema coverage. 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 clear verb+resource: 'List account webhooks', which distinguishes it from get_webhook, create_webhook, and delete_webhook. It also mentions 'study scopes' and adds a scope note about signing secrets. However, it doesn't explicitly differentiate itself from siblings like list_webhook_deliveries, which an agent might confuse with a listing operation.

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

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

No guidance on when to use this tool versus alternatives such as get_webhook or list_webhook_deliveries. There is no mention of prerequisites, conditions, or exclusions. The description only says what it does, not when it should be used.

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

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

Annotations declare idempotentHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context by specifying what state is preserved (panel survey, target cycle, progress, reward hold), which goes beyond annotations.

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

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

The description is a single, front-loaded sentence that efficiently communicates the core action and its preserved state. Every word earns its place.

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

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

With annotations covering safety and an output schema present, the description need not explain returns. However, it omits usage guidance relative to sibling lifecycle tools, leaving a gap for an agent deciding between pause, stop, and delete.

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?

One parameter (organization_id) has a schema description, but study_id lacks one. The description does not explain either parameter, leaving study_id's purpose solely to its name. It fails to compensate for the coverage gap.

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

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

The description states a specific action (pause) and resource (study) and adds what is preserved. However, it does not differentiate from sibling lifecycle tools like stop_study or delete_study, leaving the agent to infer the 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 description offers no usage context, such as when to pause versus stop or delete, nor does it mention the complementary resume_study tool. The agent must infer appropriate use from the verb alone.

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

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

Annotations only declare the safety profile (readOnly=false, destructive=false, openWorld=true), so the description carries the async burden and does it well: durable task vs job ID, the polling endpoint per client type, and the idempotency-key recovery path for uncertain responses. It stops short of stating rate limits, whether the queued turn can be cancelled, or what happens on conflicting concurrent turns.

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

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

Five short sentences, front-loaded with the action, then retrieval path, then recovery and exclusion rules. No filler and no repetition 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?

With an output schema present the description needn't describe return payloads, and it instead covers the integration path an agent actually needs (poll, then fetch the saved plan). The remaining gap is the two enums (decisions, execution_policy) whose behavior is never explained outside 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 only 43% across 7 parameters, so the description should compensate. It adds real meaning for idempotency_key (reuse only on timeout; new key for a new operation) and reinforces the concept_image restriction, but says nothing about decisions, execution_policy, message, or study_id, leaving several parameters to the schema alone.

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

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

The description states a specific verb and resource ("Queue one research-design turn") and immediately frames it as the asynchronous counterpart to customize_study, so an agent can place it against the synchronous sibling. "Research-design turn" is somewhat domain-specific jargon, but the polling follow-up clarifies the intent.

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

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

It gives explicit branch conditions: 2026 Tasks clients poll tasks/get, other clients poll get_customize_study_job, then call get_study for human review. It also names the exclusion case (native concept images require the synchronous customize_study) and the idempotency_key reuse rule, so the agent knows when this tool is and is not the right choice.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, but the description adds the crucial consequence the annotations cannot convey: the old provider link stops working immediately and the caller must update the provider with the returned entry_url. That is exactly the kind of beyond-annotation detail an agent needs before invoking a destructive op.

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

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

Three tight sentences, front-loaded with the destructive consequence, then recovery guidance. No filler or restated boilerplate.

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 annotations covering the safety profile, an output schema covering return values, and the description covering the destructive side effect and idempotency recovery, an agent has everything needed to invoke this correctly. Nothing material is missing.

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

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

Schema coverage is 67%, with idempotency_key and organization_id already documented in the schema. The description reinforces the idempotency_key contract (unique, reuse after an uncertain response) and implies study_id refers to an owned BYOP study, adding value beyond the schema without contradicting it.

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

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

States a specific verb and resource ('Replace the external-panel entry token') and scopes it ('for an owned BYOP study'). An agent can distinguish this from siblings like configure_external_panel or get_external_panel without opening any schema.

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

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

Gives clear operational direction -- supply a unique idempotency_key, reuse it after an uncertain response, and inspect with get_external_panel if the replay is stale. It names a sibling alternative, though it frames the alternatives around replay recovery rather than a broad when-to-use-this-vs-configure_external_panel rule.

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

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

Annotations already declare non-read-only, idempotent, open-world, non-destructive, so safety is covered. The description adds a genuinely non-obvious side effect: resuming also continues the preserved panel recruitment, telling the agent this is more than a status flag flip. It stops short of noting permission requirements or failure modes.

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 sentence with zero filler; the action is front-loaded and the secondary effect follows immediately. Nothing is repeated from the title or schema.

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

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

An output schema exists, so return values need no explanation, and annotations cover the safety profile. For a one-required-parameter mutation the description is nearly sufficient, lacking only the failure/precondition behavior when the study is not in a resumable state.

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 50%; organization_id is documented in the schema, while study_id has only its type/format. The description adds no parameter meaning, but study_id is self-evident and the description implies which study is affected. Baseline 3 for partial coverage where the undocumented parameter is unambiguous.

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 (resume) and resource (study) plus the state it transitions from (paused), which distinguishes it from pause_study/stop_study without naming them. It is clear but does not explicitly differentiate itself from the other lifecycle 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 phrase 'a paused study' implies the precondition that the study must currently be paused, which is useful context. However, it never states when not to use it (e.g. stopped or already-running studies), nor names alternatives such as pause_study, stop_study, or launch_panel.

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

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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint=false, so the safety bar is low. The description still adds real value by disclosing that the view does not approve or launch, preventing the agent from assuming a side effect, and by flagging the separate human-approval requirement.

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

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

Three tight sentences with the primary action front-loaded, followed by two disambiguating boundary statements. No filler; each sentence contributes a distinct constraint.

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

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

An output schema exists and annotations are rich, so the description needn't explain return values or the safety profile. It adequately covers purpose and scope boundaries; only the study_id parameter goes unexplained, which is low-risk.

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

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

Schema description coverage is 0% and the description never mentions study_id, so it adds no semantics beyond the schema. The single required parameter is a self-explanatory UUID, which limits the harm, so a 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 ('Open') and resource ('interactive, read-only view of the saved study plan and current fielding progress'), which clearly separates it from data-fetch siblings like get_study and get_fielding_progress. It does not name a sibling explicitly, but the 'interactive view' framing is distinctive.

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?

Clearly delimits scope with 'The view does not approve a plan or launch recruitment' and directs the agent to obtain human approval separately before fieldwork. This tells the agent when this tool is and isn't the right one, though it doesn't name a specific alternative tool to use instead.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive, open-world. The description adds genuinely non-obvious behavior beyond them: the new secret is shown only once and the receiver must be updated, a one-time-reveal trait an agent must act on. It omits whether the previous secret is invalidated immediately or during a grace period, which matters for a rotation 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 tight sentences with zero waste; the core action is front-loaded and the critical one-time-reveal caveat follows immediately.

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

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

With an output schema present, return values need not be re-explained, and the description still usefully notes the secret appears in the response. For a single-required-parameter mutation it covers purpose, reveal semantics and follow-up, missing only old-secret validity and permission scope.

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 50% and the description adds no parameter detail at all. The covered parameter (organization_id) is well documented in-schema, and webhook_id is self-evident from its uuid format, so the baseline of 3 applies rather than a penalty.

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 ('Replace a webhook signing secret') that unambiguously identifies the operation. No sibling tool performs secret rotation, so it is clearly distinguishable from create_webhook/delete_webhook/update-style 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 second sentence gives operational context: the secret is revealed only in this response and the receiver must be updated before relying on further deliveries, which is effectively guidance on when this must be followed up. It stops short of stating explicit when-to-use vs when-not-to-rotate conditions or permission prerequisites.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds real value beyond them: the grouped studies[] shape, the index_status lifecycle values, and the explicit note that no generated prose is returned, plus pagination termination behavior.

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

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

Three tight sentences, front-loaded with purpose, then result shape, then pagination. No filler, though the result-shape sentence is dense and could be trimmed since an output schema exists.

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

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

Given an output schema exists, return values needn't be described, yet the description usefully characterizes the grouping and pagination. The main gap is filter/query semantics for a tool whose schema coverage is low, but overall it is adequate for correct invocation.

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

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

Schema description coverage is only 40%, so the description must compensate, but it only clarifies the cursor parameter (next_cursor) and names query/filters/limit without explaining their semantics. It says nothing about study_ids, content_types, or the date-range filters, leaving the nested filter object opaque.

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 ('Search one or more studies') and describes the result shape. However, it never distinguishes itself from close siblings like answer_research or list_studies, so an agent must infer when this cross-study search differs from those.

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

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

Provides strong continuation guidance (pass next_cursor back with the same query, filters, and limit; stop when null), which is genuinely useful usage context. But it gives no when-to-use/when-not guidance relative to sibling tools such as answer_research or list_studies.

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, idempotentHint and openWorldHint, but the description adds real value beyond them: it explains the human-approval requirement and that the backend deduplicates rewards for already-paid participants. It stops short of stating what exactly is destroyed 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 sentences, zero filler, and the safety-critical approval precondition is front-loaded before the retry mechanics.

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

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

An output schema exists so return values need not be described, and the approval gate plus idempotency behavior cover the risky parts of this destructive write. The admin-only organization_id semantics are left entirely to the schema, which is a minor residual gap.

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

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

Schema coverage is 67%; idempotency_key and organization_id are already documented in the schema. The description reinforces the idempotency_key reuse semantics but says nothing about participant_id or the org-scoping parameter, so it adds only marginal meaning over the schema. 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 (Send) and resource (configured incentive) scoped to a BYOP participant, and pairs it with a hard precondition. An agent can distinguish this from sibling write tools like update_participant or create_participants 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?

Gives an explicit gate ('only after the human explicitly approves rewarding this participant') plus retry guidance ('reuse idempotency_key on uncertain retries'). The condition that selects this tool is stated rather than inferred.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds genuine behavioral detail beyond them: recruitment stops, the target cycle closes, and the reward hold is settled/released — telling the agent what actually changes. It does not, however, state irreversibility or what happens to already-collected interviews/participants.

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

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

Two sentences, zero filler. The destructive scope is front-loaded and the gating condition follows, so the highest-risk information arrives 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?

An output schema exists, so return values need no explanation, and annotations carry the safety/idempotency profile. Given the tool's complexity, the description covers effects and the human-approval gate completely enough for correct invocation.

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

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

Schema coverage is 50%: organization_id is fully documented in the schema, while study_id carries only a format/pattern. The description says nothing about either parameter, but study_id is self-evident from the tool's purpose and the admin-only scoping of organization_id is already in the schema. Adequate, not additive.

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 precise verb and resource (stop panel recruitment / close target cycle) and enumerates the concrete side effects, including settling or releasing the reward hold. This is materially distinguishable from siblings like pause_study (reversible halt) or delete_study (removal), so an agent can route correctly 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?

Provides an explicit precondition: call only after the human explicitly chooses to end this study's fieldwork. That is a real gating rule. It stops short of naming alternatives (pause_study, delete_study) or stating when NOT to call it, so it is clear context but not full when/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?

The description adds context beyond annotations by explaining that this creates a review request, not a paid launch, and specifies the need for target audience, count, and incidence rate. Annotations already indicate non-destructive, open-world, non-idempotent 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?

Two sentences with no waste, front-loading the core purpose and then providing essential usage and parameter guidance.

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

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

Given the complexity and the presence of an output schema, the description covers the main points but omits details about some parameters (like country_code) and doesn't explain return values, though output schema exists.

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 description explains the meaning of key parameters (target audience, target count, incidence rate in percentage points) and mentions an optional study link. However, with only 17% schema description coverage, it doesn't cover all parameters fully (e.g., country_code, organization_id).

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 clearly states the verb 'Submit' and the resource 'audience for manual feasibility review,' distinguishing it from siblings like launch_panel. It also clarifies that this creates a review request rather than a paid launch.

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

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

It explicitly states when to use this tool ('when direct panel launch is unavailable') and references alternative tools for checking status ('list_feasibility_requests or get_feasibility_request').

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

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

With annotations covering the safety profile (openWorldHint=true, readOnlyHint=false, idempotentHint=false), the description adds real value by disclosing that the emitted event is signed and carries no participant or study data, and that it triggers an outbound request to the registered URL. It stops short of noting side effects like delivery records being created or rate limits, but the added context is meaningful.

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 written sentences with zero filler, and the most consequential fact — that a real outbound request is made — is placed prominently.

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

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

An output schema exists, so return values need no explanation, and the annotations already declare the open-world, non-idempotent nature. The description covers payload contents and the outbound call, leaving only minor gaps such as permission requirements for the webhook owner.

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 only 50%: organization_id is documented in the schema, but webhook_id has no description at all. The description mentions no parameters, so it does not compensate for the coverage gap on the required identifier.

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 ('Send a signed test event') and clarifies the scope of the payload ('containing no participant or study data'), which is more than a restatement of the name. It does not explicitly contrast with any sibling, but no sibling overlaps with this action, so differentiation is largely unnecessary.

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 (test a registered webhook) but never stated as when-to-use guidance, and there is no mention of when not to use it or of alternatives such as list_webhook_deliveries for inspecting past deliveries. Adequate 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?

Annotations already declare idempotentHint=true and destructiveHint=false, so the write/safety profile is covered. The description adds genuinely new behavior: partial PATCH semantics, the null-clears-field rule for email, and a read-before-write verification step. It stops short of describing permission requirements or what happens to unspecified fields in metadata.

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

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

Three short sentences, front-loaded with the action and scope, then the prerequisite, then the two edge-case rules. No filler or restated name/title content.

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

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

Output schema exists, so return values correctly need no description. Combined with annotations, the description covers the mutation semantics, verification prerequisite, and clearing behavior. The remaining gap is the shape/merge behavior of the nested metadata object and external_id, which are neither in the schema nor the description.

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 only 20% (only organization_id is documented in-schema). The description clarifies email semantics (null clears) and the partial-update rule, but says nothing about how metadata is merged or replaced, or about external_id's role, leaving three parameters thinly explained in both places.

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 (change), a specific resource (one BYOP invitation / participant), and names the exact fields touched (email, CRM fields) plus the HTTP verb PATCH. An agent can distinguish it from delete_participant and get_participant without opening the schema.

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

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

Gives explicit prerequisites ('Call get_participant first to verify the intended participant'), an explicit guard on a risky case ('Send email=null only when the user explicitly wants to clear it'), and a general invocation rule ('Pass only fields to change'). This is prescriptive when-to-use guidance rather than vague 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 write, idempotent, non-destructive, and open-world traits. The description adds important behavioral context beyond those annotations: partial-update semantics ('Only supplied fields change'), a state precondition requiring active panel studies to be paused/stopped, and a recommended read-before-write workflow. It does not cover auth or rate limits, but the added constraints are substantive.

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

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

Four short sentences, front-loaded with the core action and scope. Each sentence earns its place by adding routing, update semantics, or a precondition. 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?

Output schema exists, so return values need not be explained, and annotations cover the safety profile. However, for a mutation tool with nine parameters and only 44% schema coverage, the description leaves an agent without guidance on many fields. It handles routing and preconditions well but is incomplete on parameter-level detail.

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 only 44%, so the description must compensate but largely does not. It clarifies that only ordinary metadata is in scope and excludes several fields, but it adds no meaning about the individual parameters such as name, language, study_type, or byop_config. 'Only supplied fields change' is useful PATCH semantics but does not document what the parameters accept.

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 first sentence states a specific action and scope: 'PATCH ordinary study metadata only.' It immediately distinguishes this tool from customize_study, naming the exact fields handled elsewhere, so an agent can differentiate it from siblings without inspecting schemas.

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

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

The description explicitly names the alternative (customize_study), states when not to use this tool, and gives two clear preconditions: active panel studies must be paused or stopped first, and get_study should be called first. This goes beyond implied usage to explicit routing and prerequisites.

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