User Intuition

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the mutation and its safety profile are known. The description adds useful scope ('every currently available study', legacy label) but does not say what happens to studies already in the session or whether repeats duplicate entries, which matters given idempotentHint=false.

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 legacy/scope caveat and followed by the disambiguation pointer. 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?

The output schema exists, so return values need not be explained, but for a non-idempotent bulk mutation the description should cover duplicate handling and the redundant-add case. Permission or session-state prerequisites are also unaddressed.

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%: session_id carries no description and the description does not explain it beyond the loose phrase 'this Hub session'. organization_id is documented in the schema with a pointer to list_organizations, so the description adds nothing the schema doesn't already provide.

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 scope ('add every currently available study to this Hub session') and contrasts it with the alternative bulk-vs-single path. An agent can tell this apart from sync_research_study and remove_research_study 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?

Explicitly names the sibling to use instead for a single study ('Use sync_research_study for a selected study'), giving a clear bulk-vs-single decision rule. It stops short of saying when this legacy path should be avoided altogether.

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, and closed-world, so the safety profile is fully covered. The description adds that results include citations, source details, and index status — a hint that output quality depends on indexing state — but does not state access/billing implications or latency expectations. It adds modest context beyond annotations without addressing operational 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 with zero waste: what it does, what it returns, and where to go instead. The core operation is front-loaded and nothing is repeated from the annotations.

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-value explanation is not required, and annotations cover safety. However, for a tool with a required nested filters object at 33% schema coverage, the description leaves the agent without guidance on content-type selection, study-count limits, or date scoping — gaps the description should have filled.

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%: only organization_id is documented in-schema. The description vaguely maps 'selected accessible studies' to filters.study_ids but says nothing about the 20-study cap, the content_types enum, or the research date range filters, which are the substance of the nested object.

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: 'Answer a question across selected accessible studies using indexed research.' It also names the sibling it is not (search_research) and clarifies the scope of the operation, so an agent can distinguish it from search/view siblings without opening any schema.

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

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

Explicitly routes the agent to search_research 'to inspect the underlying records,' giving a clear alternative-use condition. It does not address the other plausible alternative (view_research_answer) or state when answering is inappropriate, but the primary routing guidance is 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 already declare destructive=true, non-idempotent, open-world. The description adds real context beyond them: the nonce is single-use and short-lived (explaining non-idempotency), the saved study and price are re-validated before committing, and the launch is a paid cycle. It stops short of saying what happens if the nonce is expired or the recheck fails.

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

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

One sentence and one leading fragment, with the invocation context front-loaded before the operational detail. Nothing is redundant, though the 'MCP App button action' fragment is terse enough that its meaning is not fully self-evident.

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 destructive paid action. The description supplies the sequencing (consume nonce -> recheck study/price -> launch one cycle), leaving only edge-case/failure behavior unspecified.

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

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

Schema coverage is 0%, so the description must carry the only explanation of approval_nonce. 'Consumes one short-lived approval challenge' does convey that the value is a one-time, expiring challenge rather than an arbitrary id, but it does not say where the agent obtains it or what a consumed/reused nonce returns.

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 concrete verb+resource ('launches one paid panel cycle') and characterizes the mechanism ('MCP App button action', consuming an approval challenge). It is clearly not a generic launcher, but it never names or contrasts the very similar sibling launch_panel, so an agent must 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?

'MCP App button action' implies this is invoked from a UI approval flow rather than called ad hoc, and 'consumes one short-lived approval challenge' implies a prerequisite exists. However, there is no explicit statement of when to use this versus launch_panel, nor any exclusion about when not to call it.

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 agent knows this is a destructive but idempotent mutation. The description adds the pending-only lifecycle constraint, which is genuinely beyond the annotations, but says nothing about the effects of withdrawal (does it free held capacity, can it be resubmitted, is it reversible).

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

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

Two short sentences, front-loaded with the action and followed by the blocking condition. Nothing is wasted and nothing 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 not be explained, and the annotations carry the safety profile. For a two-parameter tool the description covers the key precondition; only the permissions needed and post-cancel effects are left unstated.

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-schema, but request_id has no description in the schema and none in the tool description. The description adds zero meaning about which request identifier to supply or how to obtain one.

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 ('Withdraw a pending feasibility request'), which is inherently distinct from the sibling verbs submit_feasibility_request, get_feasibility_request and list_feasibility_requests. It does not name those siblings explicitly, so it stops 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?

'A request already answered cannot be cancelled' gives a clear when-not condition tied to request state. It does not point the agent at alternatives (e.g. call get_feasibility_request first to confirm the request is still pending), so no explicit alternative routing.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is structured. The description adds the non-obvious post-condition that existing results remain available for inspection, which materially narrows how destructive the call actually is. It does not say what happens to an in-flight run or whether cancelling a finished run errors.

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 action and its gating condition front-loaded before the aftermath note. Every sentence carries distinct 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?

With rich annotations (destructive, idempotent, closed-world) and an output schema present, the description only needs purpose, invocation gate, and side-effect scope, and it covers all three. Return values and parameter formats are correctly left to structured fields.

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 run_id relies on its name and UUID format. The description only reinforces that a single run is targeted, adding little beyond the schema. 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 ('Cancel one durable analysis run'), and the word 'one' plus 'durable analysis run' distinguishes it from bulk operations and from session/study cancellation siblings. It never names an adjacent sibling such as resume_research_analysis or get_research_analysis, so differentiation is implied 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?

'only when the user requests it' gives an explicit gating condition for invocation rather than leaving timing to inference. It stops short of naming alternatives or stating when-not to use it (e.g., completed runs, or use resume_research_analysis instead), so no exclusions are covered.

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 and idempotentHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond annotations: a cancelled worker cannot publish its file, which tells the agent the consequence of cancellation. It stops short of describing irreversibility or permission requirements.

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

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

The definition is two short sentences, front-loaded with the action and scoped by job state, followed by the key behavioral consequence. 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 explained. Still, for a destructive cancellation tool, the description omits parameter meaning for the required job_id and offers no guidance on alternatives, leaving meaningful gaps.

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 50% schema description coverage, the description must compensate, but it mentions no parameters at all. The required job_id has no description in the schema beyond UUID format/pattern, so the agent gets no natural-language explanation of what identifier to pass; only organization_id is documented 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?

The description states a specific verb and resource—'Cancel a queued or running Hub export'—making the action unambiguous. It does not distinguish this tool from sibling cancel tools such as cancel_research_analysis or cancel_feasibility_request, leaving differentiation to the agent's inference.

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 implies the applicable conditions by saying 'queued or running,' which is useful context for when cancellation is valid. However, it provides no explicit when-not-to-use guidance and does not mention alternatives for cancelling other research artifacts.

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?

Adds substantial context beyond annotations: non-cancelling wait semantics, durable job reuse across polls, retry guidance after a timeout (same idempotency_key and prompt), sync/async sharing the job, and parent_job_id for follow-ups in the same session. The idempotentHint=false annotation sits slightly at odds with the retry-key advice, but the description explains the dedupe mechanism rather than contradicting it. Minor gap: wait_seconds timeout behavior is not discussed.

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 behavior is front-loaded, which is good, but the body is a dense run-on of semicolon-chained workflow rules (~140 words) mixing routing, session setup, polling, and answer rendering. Most sentences carry operational value, yet the packing makes it hard to scan and would benefit from tighter grouping.

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 complex async job tool with an output schema (so return values need no explanation) and low schema coverage, the description covers the end-to-end lifecycle: session setup, submission, polling, retry, and mandatory follow-up rendering. Only wait_seconds behavior and two auxiliary parameters remain undocumented.

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%, so the description must carry the load. It explains session_id (reuse selected Hub session, create if absent), idempotency_key (stable retry key, reuse after timeout), prompt (reuse the same prompt), and parent_job_id (follow-up in same session). But wait_seconds, organization_id, and include_synthetic get nothing, so compensation is only 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?

The opening sentence states a specific behavior: wait for a chat answer, and if still running return the same durable job without cancelling it. This distinguishes it from queue_research_chat (enqueue) and view_research_answer (render), though the actual verb/resource framing is buried under workflow instructions rather than stated crisply up front.

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

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

Explicit routing is present: use it for 'study findings, feedback, comparisons and quotations', resolve ambiguous study names first, reuse the selected Hub session or create one with create_research_session, and always follow with view_research_answer. It also names negative behavior ('Do not resync unchanged sources or broaden the session silently') and gives the alternative polling tool (inspect_research_session view=job).

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 and idempotentHint=true, so the safety profile is known. The description adds genuinely non-obvious scope information: sources are detached from the session but the underlying studies and files survive, which is exactly the distinction an agent needs before calling a destructive tool. It omits permission/org requirements and whether the clear is reversible.

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 destructive scope stated before the usage restriction. 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?

An output schema exists and annotations cover safety, so the description only needs to convey purpose and blast radius, which it does. The one remaining gap is operational prerequisites for organization_id, though the schema points to 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 coverage is 50%: organization_id is documented in the schema, but session_id carries no description and the description only says "this Hub session" without noting the UUID format or that the session must already exist. The description adds almost nothing beyond the schema, which is the baseline expectation at this coverage level.

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 scope ("bulk removal" of "all sources from this Hub session") and distinguishes the operation from destructive file/study deletion. It does not explicitly name its closest siblings (remove_research_source, remove_research_study), but the word "all" versus a single source does the differentiating work implicitly.

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

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

It states a clear condition ("Use only when the user requests clearing the session") and labels the tool "Legacy", which warns an agent to prefer newer paths. It never names the alternative tool to use instead, so the routing is implied rather than spelled out.

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

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

Annotations already flag destructive, idempotent, and open-world behavior, and the description adds genuinely new context: the human-approval gate, the read-before-write verification step, and that repeating the same PUT preserves the current entry token. It does not say what an actual config change does to the existing panel or its token, which matters for a destructive replace.

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 the action, then requirements, then optional mappings, then the safety gate, then scope exclusions. Every sentence adds a distinct constraint or clarification.

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 destructive mutation with an output schema and full annotations, the description covers scope, prerequisites, approval gate, idempotency, and exclusions. The remaining gap is permission/billing context and the effect of a changed config on the existing token.

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 8%, so the description has to carry this dimension. It identifies the required redirect URLs, explains when respondent_id_param and its placeholder need setting, and groups the optional mappings (session, external study, quota-full, technical-failure) — real semantic value, though it never names those parameters or gives placeholder syntax.

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

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

States a specific verb and resource ('Create or replace a customer-supplied panel bridge') plus the scope constraint ('on an owned BYOP study'). This clearly separates it from sibling tools such as get_external_panel, delete_external_panel, regenerate_external_panel_token, and launch_panel.

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_study, verify provisioning_status=provisioned, get human approval of the plan and URL mapping before sharing entry_url) and names what the tool does not do (recruit respondents, launch the paid panel). It stops short of naming the exact alternative tool for the paid panel path, so the routing is implied rather than 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 declare destructiveHint=true and openWorldHint=true but say nothing about side effects or preconditions. The description supplies the key behavioral facts: invitations are sent as a side effect unless silent is true, the operation is asynchronous and must be polled, and approval validity is tied to study_id and 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?

Four sentences, front-loaded with the action, then sequencing, then preconditions, then side effects — a sensible order with no filler. The approval-carry-forward sentence is dense and slightly hard to parse, costing 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?

For an async, destructive, open-world batch mutation, the description covers preconditions, the polling loop, the invitation side effect, and approval invalidation rules; an output schema exists so return values need not be explained. An agent has everything required to call this 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%, and the description compensates for part of the gap by explaining the silent flag's effect, the 1–100 uniqueness bound on participants, and the study_id/updated_at linkage used for approval carry-forward. It says nothing about idempotency_key, metadata, or external_id, which are the remaining undocumented fields.

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 nature ('queue') and the batch bound distinguish it immediately from create_study, add_all_research_studies, and update_participant.

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-call gate (call get_study, require provisioning_status=provisioned, obtain/verify plan approval) and an explicit post-call procedure (poll get_participant_job until succeeded, then list participants). It also names the exact conditions under which a carried-forward approval stays valid versus is invalidated.

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 mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the safety baseline is covered. The description adds one genuinely non-obvious behavioral fact: that idempotency is key-driven, so a retry with the same key is safe despite idempotentHint=false — this prevents accidental duplicate sessions. It does not disclose what happens to the referenced studies/sources, permission requirements, or failure modes, so it stops short of rich behavioral context.

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 core action front-loaded and the retry rule second. Every clause 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 not be explained, and the idempotency retry rule is covered. The gap is the mismatch between the description's promise of attaching 'selected studies and uploaded sources' and a schema containing only name, idempotency_key, and organization_id — the description never clarifies that attachment happens via sibling tools such as add_all_research_studies or upload_research_source.

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 in-schema), so the description carries extra weight — and it does give the required idempotency_key a real meaning (reuse on uncertain responses), which is the single most important semantic here. However, it says nothing about the 'name' parameter, and it references 'selected studies and uploaded sources' that are not parameters at all, leaving an agent unsure how those attachments are supplied.

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 an organization Hub session') plus a scope ('for selected studies and uploaded sources'), which separates it from siblings like delete_research_session, rename_research_session, and inspect_research_session. It loses a point because 'Hub session' does not exactly echo the tool's own 'research session' vocabulary, and no sibling is named as an explicit alternative.

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 only guidance is a retry instruction ('Reuse the same idempotency key after an uncertain response'), which is about recovering from a failed call, not about when to choose this tool over inspect_research_session or chat_research_session. There is no statement of prerequisites (e.g., an active organization membership) or of when not to call it.

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, which only declare it is a non-read-only, non-idempotent, non-destructive write. It discloses the human-confirmation rule and that a host-proposed value does not count, that the Customize Plan backend validates and attaches assets, defaults applied when format/language/voice are omitted, and that voice config persists into chat.

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 purpose and the human-confirmation rule, and nearly every sentence carries operational weight. It is long, with mild redundancy (the closing note that voice config applies to chat restates the schema's own wording) and some asset-handling detail that arguably belongs with customize_study.

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 creation tool with an output schema, the description covers the pieces an agent could get wrong: mandatory human choice, format/type compatibility, default injection, and handoff to customize_study. Return values need not be explained given the output schema, though billing/organization implications are left entirely to 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 already 88%, so parameters are largely self-documenting. The description still adds meaning the schema does not: recruiting_method must be a human choice not a guess, and the omission defaults for interview_format, language, and voice. It stops short of explaining organization_id or name constraints, but those are covered 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 and resource with explicit scope: creates a draft study of one of three named types, using only ordinary metadata. It also carves out what the tool does NOT do (study plan, targeting, screeners, concepts) and names customize_study as the place for that, so it is clearly separable from its closest sibling.

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

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

Gives concrete when-to-use routing (brief goes to customize_study after creation), hard constraints (synthetic respondents require chat; prototype-test never chat), and default behavior when optional fields are omitted. It also states an explicit precondition — a human must choose recruiting_method — rather than leaving it 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 that this is a non-read-only, open-world, non-idempotent, non-destructive creation operation. The description adds important behavior beyond those hints: the signing secret is shown only once and must be stored securely. It still omits authentication requirements and how duplicate webhook creation is handled.

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 with no filler, front-loading the core create action and scope before the event choices and the security warning. Every sentence adds useful 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?

The description covers the essential create behavior, scope options, event categories, and the one-time secret. With annotations and an output schema present, it does not need to explain return values, but it could be more complete by noting authentication needs or duplicate-call 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 25%, so the description must compensate. It clarifies that the webhook can target an account or one owned study, which gives meaning to study_id, and groups event_types into interview, study lifecycle, participant lifecycle, and quota categories. It does not explain hook_url semantics, exact event-type usage, or the event_types array constraints beyond what the schema already encodes.

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 uses a specific verb and resource: 'Create a webhook' for an account or one owned study. It clearly states scope and event categories, but does not explicitly distinguish this from sibling operations like test_webhook, list_webhooks, or rotate_webhook_secret, leaving the agent to infer from the verb alone.

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 some usage context by saying to choose interview, study lifecycle, participant lifecycle, or quota events, and notes account-level versus study-level scope. It does not state when to prefer this tool over alternatives such as test_webhook, nor does it mention prerequisites or exclusions.

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?

Adds substantial context beyond the annotations: external concept-URL fetches, an external analysis model, durable-task vs synchronous behavior depending on concept_image presence, and that completed plans and setting changes are persisted (consistent with destructiveHint=true and readOnlyHint=false). It does not spell out exactly what a turn overwrites in an existing plan, which is the main residual gap for a destructive mutation.

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?

Every sentence is roughly actionable, but the definition is a dense wall of mixed concerns — image handling appears between workflow-policy rules and post-call approval steps, so ordering is not front-loaded by task phase. It could be tightened or split into grouped clauses without losing 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?

Given an output schema exists, return values needn't be described, and the description instead covers call shape, async vs sync path, image encoding, and the approval gate — close to complete for a complex write tool. The main omission is what state an existing plan loses when a turn is applied.

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 already 86%, so the baseline is 3; the description still adds decision-mode semantics for `decisions` and the encoding/labeling workflow for `concept_image` (ask for a participant-facing label, base64-encode raw bytes). The execution_policy/message separation rule is also meaningful usage semantics rather than schema restatement.

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

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

Opens with a concrete verb and resource: "Send one research-design turn to Customize Plan," and makes the turn-based nature explicit. It does not, however, differentiate itself from the close siblings queue_customize_study or get_customize_study_job, which an agent would likely wonder about.

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 real routing rules: decisions=agent only when the human delegated research-design choices, otherwise human mode with questions[] relayed, and workflow constraints belong in execution_policy rather than message. It also states the follow-up sequence (get_study, show plan, obtain approval before invitations or paid launch). What's missing is explicit comparison against the queue/get job 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?

Beyond the destructive and non-idempotent annotations, the description clarifies exactly what is affected: existing interviews remain, the provider can no longer send new respondents through the link, and repeated deletion returns 404. This is high-value behavioral detail for a destructive 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?

The description is three tight sentences with the core effect front-loaded. Each sentence adds relevant information: purpose, preservation of existing interviews, and repeated-deletion behavior.

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 destructive annotations, partial schema descriptions, output schema, and sibling tools, the description provides enough context to invoke the tool correctly. It covers the critical side effects and repeated-call behavior without needing to explain return values.

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 organization_id documented in the schema and study_id documented only by type/pattern. The description adds the useful constraint that the study must be an owned BYOP study, but it does not explain organization_id or add further detail about study_id beyond that constraint.

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 and resource: disabling the external-panel entry link for an owned BYOP study. It clearly conveys the operational effect, but it does not explicitly distinguish the tool from close siblings such as configure_external_panel, get_external_panel, or regenerate_external_panel_token.

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 implied usage context by saying it applies to an owned BYOP study and leaves existing interviews intact while preventing new respondents from using the link. It does not explicitly state when to use this instead of related tools such as regenerate_external_panel_token or configure_external_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?

The annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds the critical non-obvious detail that this is a SOFT delete (implying recoverability), which the annotations do not convey. It does not describe downstream effects on related data or where the deleted record goes.

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 padding, with the operation and the hard call-time precondition front-loaded. 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?

An output schema exists, so return values need not be explained, and the annotations carry the safety profile. The soft-delete semantics and human-approval requirement make it largely complete for a single-ID mutation. Minor gap: no mention of whether organization_id is required or how ownership failure behaves.

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 interview_id has no description. The description says the interview must be owned by the authenticated user, which adds a precondition constraint on interview_id, but gives no hint on where to obtain the ID (e.g., list_interviews). Baseline 3 for partial coverage plus a small constraint.

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', with an ownership scope ('owned by the authenticated user'). It clearly separates this from list_interviews/get_interview siblings, though it does not explicitly distinguish itself from the many other delete_* tools beyond the resource name.

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 gating condition: 'Call only when the human explicitly requests deletion of this interview.' This is a clear when-to-use rule. It does not name an alternative (e.g., no restore/undo path or 'prefer archiving' guidance), so it falls short of a 5.

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

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

Beyond annotations, which already flag destructive and idempotent behavior, the description adds that this is a soft-delete, removes the personal link, and may return a conflict unless cascade deletion is explicitly approved. Those are meaningful behavioral details for a destructive 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 compact sentences, front-loaded with the core action and followed immediately by the most important behavioral caveat. No sentence 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?

The description covers the destructive action, the soft-delete semantics, the link-removal effect, and the cascade prerequisite. With an output schema present and annotations covering safety, no additional description is needed 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 only 33%, so the description carries meaningful burden. It clearly explains cascade_interviews' gating behavior and the conflict condition, while participant_id is implied by the singular BYOP invitation scope. organization_id is not described here, but the schema already supplies its 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 uses a specific verb and resource ('Soft-delete one BYOP invitation') and clarifies the scope narrowly, distinguishing it from broader deletion tools. It also explains what is removed, namely the participant's personal link.

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

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

It explicitly says deletion should occur only after the user explicitly requests it, and explains the conflict condition when interviews exist. It also states that the user must separately approve deleting interviews and that cascade_interviews must be true.

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 and idempotentHint=true, so the safety profile is known. The description adds value beyond them by stating permanence, the user-authorization requirement, and a read-before-delete workflow step. It still says nothing about what happens to items referencing the output or about 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, front-loaded with the destructive action and its precondition; 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?

An output schema exists, so return values need not be explained, and the safety profile is carried by annotations. However, for a destructive 3-parameter tool with low schema coverage, the description leaves the identifier parameters and their relationships 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 coverage is only 33% (only organization_id is documented in-schema), so the description should compensate, but it never explains output_id, session_id, or the UUID format constraints. Only the phrase 'in its session' faintly implies the session scoping of the operation.

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 plus resource and scope: 'Permanently delete an existing Studio output in its session.' An agent can distinguish this from edit_research_output, rename_research_output, and the delete_* siblings without opening a schema.

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

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

'only when the user requests deletion' is an explicit when-to-use gate, and 'Read the output first' gives an ordering precondition before invocation. It does not name alternatives (e.g., edit/rename instead of delete), so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, openWorldHint=false and readOnlyHint=false, so the safety profile is known. The description adds a user-consent guardrail, which is genuinely useful, but says nothing about whether deletion cascades to studies/outputs or is recoverable — the details an agent most 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?

One short sentence with the destructive verb front-loaded and the consent condition attached. Nothing is wasted, though the single sentence is doing very little work for a destructive two-parameter operation.

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 irreversible destructive mutation with a half-documented schema, the description should say what is removed with the session and how to identify the target. An output schema exists, so return values needn't be explained, but the preconditions and blast radius are missing.

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

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

Schema description coverage is only 50%: organization_id is documented in the schema, but session_id has no description anywhere. The description mentions 'organization' context but never explains how to obtain a session_id (inspect_research_session, create_research_session, etc.), so it fails 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?

A specific verb (Delete) plus a specific resource (organization Hub session) with a clear cardinality constraint ('one'). It does not, however, distinguish itself from the many other delete_* siblings (delete_study, delete_interview, delete_research_output), so an agent must infer the boundary.

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 'only when the user explicitly requests it' is a real usage gate that tells the agent not to delete proactively. But it offers no alternative path (e.g., inspect_research_session to confirm the target, or delete_study for a narrower deletion), which matters given the large delete-heavy sibling set.

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 and idempotentHint=true, so the safety profile is known. The description still earns credit for non-obvious behavior the annotations cannot convey: cascade scope, participant links breaking, no public restore endpoint, and separate asset retention. No contradiction with annotations — 'soft-delete' and 'no restore endpoint' are consistent with 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?

Five short sentences, each carrying distinct information: cascade scope, link breakage, irreversibility, asset caveat, and the human-approval gate. The destructive consequence is front-loaded and there is 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?

A mutation tool with an output schema present, so return values need no explanation; annotations plus the description together cover safety, irreversibility, and cascade effects. An agent has everything needed to decide and call 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%: organization_id is documented in-schema, study_id is an obvious UUID. The description says nothing about either parameter, relying entirely on the schema. Baseline 3 is appropriate since roughly half the parameters are self-evident and half 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?

Specific verb (soft-delete) plus resource (study) plus the cascade scope (invitations, interviews, reports). It clearly separates itself from pause_study/stop_study by stating the data is removed 'from normal reads', but it never names an alternative tool such as remove_research_study, so the differentiation is inferential 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?

'Call only when the human explicitly requests deletion of this study' is a concrete gating condition, effectively a when-not-use rule for autonomous agents. It stops short of naming the correct sibling for softer actions (stop_study, pause_study) or the alternative removal path (remove_research_study), which would have made it a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so safety is covered. The description adds genuinely new behavior: the tool is deprecated and a repeated deletion surfaces a 404 rather than silently succeeding. It does not add anything on permissions or irreversibility, so 4 rather than 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 with the deprecation front-loaded, which is exactly the right first impression. The middle sentence is slightly tangled in its clause ordering but 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 values need no explanation, and annotations carry the destructive/non-idempotent profile. What remains unexplained is the format/validity of hook_url and that the deletion is irreversible, which are minor but real gaps for a destructive 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% and hook_url has no description anywhere, so the agent must infer it is the URL identifying the webhook. The description partially compensates by pointing at list_webhooks as the source of that value. organization_id is documented in the schema itself, so the description adds little there.

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 reads as a deletion tool ("A repeated deletion returns 404") and the title supplies the "by URL" scope, so with the name the operation is identifiable. It also distinguishes itself cleanly from delete_webhook_by_id. It never states plainly what it deletes and by which identifier, so it stops 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 names the exact preferred workflow: list webhooks, then use delete_webhook_by_id, and gives the condition that makes this tool the fallback (clients that omit DELETE request bodies). That is explicit when-to-use, when-to-prefer-an-alternative guidance, which is the top of this scale.

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 and idempotentHint=false, and the description adds real value on top by explaining *why* it is non-idempotent: a repeat call returns 404 rather than succeeding silently. It also scopes the effect to future deliveries, though it doesn't clarify whether the webhook record and delivery history are permanently removed.

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

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

Two tight sentences with the primary effect front-loaded and the repeat-call caveat second. 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 rich annotations and an output schema, a brief description is defensible, and the 404 behavior is a useful addition. Gaps remain around the destructive scope (record vs. deliveries), permissions, and the ambiguity with the sibling `delete_webhook`.

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%, and the description says nothing about either parameter. The undocumented `webhook_id` is left to be inferred from the name and UUID pattern, so the description 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?

States a specific verb and resource ('Stop future deliveries to one registered webhook') in plain operational terms. It does not distinguish this tool from the near-identical sibling `delete_webhook`, which leaves an agent guessing between two deletes.

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 use case is implied — remove a live webhook endpoint so it stops receiving events — but there is no explicit when-not guidance, no prerequisite/permission notes, and no routing between `delete_webhook` and `delete_webhook_by_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 only declare it is a safe read; the description adds substantive traits: a 64 MB payload cap, base64-encoded file bytes, an MP4 link that is private and short-lived, and the fact that access is re-verified at download time. These are non-obvious constraints an agent could not get from 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?

Three tight sentences, front-loaded with what is retrievable and the format mapping, followed by the payload-encoding rule and the integrity guardrail. No sentence 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?

Covers format semantics, size limits, encoding, link lifetime, and reference integrity — enough to invoke correctly and handle the response, and the output schema carries the return shape. Minor gap: it doesn't clarify whether format is optional or whether certain formats are only valid for certain output types.

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 low (25%), so the description must carry weight, and it does for `format` by mapping each enum value (md, pptx, pdf, mp4) to a concrete artifact type and delivery mode. It says nothing about the required session_id/output_id pair or the organization_id billing scope, leaving part of the parameter set 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 and resource ('Retrieve a saved report') and enumerates the concrete artifact types (Markdown, PPTX/PDF, MP4 highlights). It doesn't name which sibling is the alternative (e.g. get_research_deliverable vs download_research_output), so the boundary 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 clear operating guidance for the result: decode base64 into an artifact instead of showing it to the user, and never fabricate download URLs. It does not say when to pick this tool over get_research_deliverable or when a given format is unavailable, so exclusions are missing.

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 past the annotations: it discloses that the ID is retained, saved evidence is reused, certain outputs are immutable, and the operation is asynchronous and must be polled. The 'Reuse the key on retry' line adds idempotency-key retry semantics; it sits in mild tension with idempotentHint=false but is not a contradiction, since a fresh key still produces a new edit.

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?

Six short sentences, action and in-place scope front-loaded, then preconditions, exclusions, polling, and retry. Nothing is padding; each sentence carries a distinct operational fact.

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 is a destructive in-place mutation with an output schema, and the description covers preconditions, immutability cases, async polling, and retry behavior. It stops short of saying whether the prior report content is overwritten or versioned, and says nothing about required permissions.

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), so the description has to carry the load. It refers to all four required params in prose — the prompt, the existing output (output_id), the session via inspect_research_session, and the idempotency key — but adds no format or semantics beyond their names.

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: 'Apply the requested prompt to an existing report or PowerPoint in place.' The words 'existing' and 'in place' distinguish it from generation/regeneration siblings such as generate_research_output, though no sibling 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 real preconditions ('Read the output first'), an explicit exclusion ('default reports and Highlights cannot be edited'), and a follow-up path ('Poll inspect_research_session view=job and read the original output after success'). It never states the edit-vs-generate decision rule against generate_research_output, which keeps it below a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new operational context: the numbers are estimates that can change before launch, the timeline is heuristic, and no paid request occurs until human approval. That is meaningful disclosure beyond the annotation set.

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

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

Front-loaded with purpose and return contents, then the routing rules. The long enumeration of return values partly duplicates the output schema, which slightly dilutes efficiency, but every sentence carries actionable 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?

Safety profile is covered by annotations and return shape by the output schema, so the description only needed to add the approval gate, estimate volatility, and feasibility routing — all present. The remaining gap is that a couple of optional parameters (frequency, organization_id) are left entirely to 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?

With 50% schema description coverage, the description compensates for the key inputs by explaining the incident_rate (<10%) and target (>1,000) thresholds that force routing to submit_feasibility_request. It does not illuminate study_id, frequency, or organization_id, so it is not fully compensating, but it adds real meaning beyond the bare schema constraints.

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 ('Read-only estimate for one Panel recruitment cycle') and enumerates exactly what the estimate contains (per-interview and total credit cost, balance/deficit, reward, card hold, recurrence, timeline). It is clearly distinguishable from launch_panel, which is named as the consumer of this estimate.

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 routes the agent: launch_panel shows this estimate for human App approval (or chat confirmation) before the paid request, and submit_feasibility_request is required for incidence below 10% or more than 1,000 interviews. Both the when-to-use and the when-to-use-something-else conditions are spelled out.

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

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

Adds real behavior the annotations cannot convey: asynchronous execution, durable task vs job-ID client branching, polling endpoints, and webhook completion signals. It does not mention cost/billing implications of the external model even though organization_id is described as billing-related in the schema, and it doesn't reconcile the idempotency_key parameter with idempotentHint=false.

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 action and then the completion paths. Dense but every sentence carries workflow information; no filler or restated 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?

Output schema exists, so return values need not be explained, and the description covers the critical async lifecycle and how to retrieve results. What remains missing is guidance on when this is the right tool versus sibling analysis/report tools, given a crowded namespace.

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%, so the schema already documents idempotency_key and organization_id reasonably well. The description adds no parameter-level meaning at all — study_id is only implied via 'study responses' and organization_id/idempotency_key are never mentioned — so it neither compensates for nor improves on 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 and resource: queue analysis of study responses via an external analysis model, with follow-up calls named (get_report_job, get_study_report). It is clearly a job-enqueueing tool, though it does not distinguish itself from similarly named siblings like start_research_analysis or generate_research_output.

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 post-call workflow: poll tasks/get for 2026 Tasks clients, poll get_report_job for others, then call get_study_report, with report.ready webhooks as an alternative signal. No explicit when-not or comparison against sibling analysis tools, so it stops short of a 5.

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

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

With annotations present but sparse, the description adds substantial behavior: this is an async queued job with a job-view polling pattern and an output_id return, Highlights uses default-report goals/quotes and original audio with no artificial narration, and the prompt cannot select different quotes. One wrinkle: idempotentHint is false while the text says to retry with the same key, which is meaningful but explained only implicitly (dedupe via idempotency_key rather than natural idempotency).

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 purpose and the reuse rule are front-loaded, and the polling/retry instructions are compact. Later clauses are telegraphic (e.g. 'with original audio when available and no artificial narration for chat studies') and require a re-read, but no sentence 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 an async generator with an output schema, the description covers the queuing model, how to poll, where to read the result, idempotent retry, and output-type-specific behavior. The remaining gap is semantics for the optional parameters (template_id, name, include_synthetic), which an agent would otherwise have to guess at.

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 13%, so the description must compensate and does so only partially: it conveys the three type values, the limits of prompt for Highlights, the retry role of idempotency_key, and implicitly session_id. name, template_id, include_synthetic, and organization_id are left entirely to the schema, so several parameters remain semantically thin.

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 gives a specific verb ('Queue') and three concrete output resources (report, native PowerPoint, saved Highlights video) scoped to a Hub session. It is clear what the tool produces, though it does not explicitly distinguish itself from close siblings like generate_report or queue_report_slides.

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 supplies a real usage rule: it reuses saved reports and findings so exhaustive analysis need not run first. It also gives the operational loop (poll inspect_research_session view=job, then read output_id) and a retry rule. It stops short of naming which sibling to use for the non-reuse or slide-specific cases.

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, closed-world, so the safety profile is covered; the description adds genuinely non-obvious behavior: it resolves the 'effective' workspace/role rather than accepting one, and it surfaces billing readiness signals that gate paid actions. It stops short of saying what happens when readiness checks fail or how stale credit balances may be.

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

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

Two front-loaded sentences: the first lists what is returned, the second kills the dangerous assumption that a stored payment method approves spend. The second sentence is a bit indirect ('use the current estimate and its MCP App') but every clause carries decision-relevant information, so there is 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, the description need not document return values, and annotations carry the safety profile; the remaining need is preconditions, which it covers via 'before a paid action' and the approval caveat. Minor gap: no guidance on behavior for users without an organization or with zero credit.

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

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

Only one optional parameter and schema coverage is 100%, with the schema's own description already covering organization selection and the list_organizations fallback for multi-membership users. The tool description adds nothing further about the parameter, 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?

Uses a specific verb (Read) plus a precisely enumerated resource surface: effective workspace, role, credit balance, payment method readiness, incentive limits. That enumeration makes it unmistakable versus siblings like get_study or list_organizations, which return different objects.

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

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

States the timing explicitly ('before a paid action') and then draws the critical boundary: a payment method on file does not authorize a Panel launch, and routing for human approval goes through the current estimate and its MCP App. That is a when/when-not rule plus a named alternative path, not 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 readOnlyHint, idempotentHint, non-destructive, closed-world, so the safety profile is covered. The description adds real behavioral value by exposing the job's outcome states (succeeded/failed) and the required follow-up action for each; it stops short of describing polling cadence or result contents.

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, outcome-first structure, zero filler; the primary action ('Poll a queued...') is front-loaded and the branching 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?

An output schema exists so return values need not be explained, and the workflow guidance is present. However, for a 3-parameter polling tool it omits the origin of job_id and any guidance on repeated polling or job expiry, leaving a real 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 description coverage is only 33% — only organization_id is documented, and job_id/study_id are bare UUIDs. The description never mentions any parameter, so it does not compensate by explaining that job_id comes from queue_customize_study or why study_id is needed alongside 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 (poll) and a specific resource (a queued study customization job/turn), which is clearly distinct from the queueing sibling queue_customize_study and from get_study. It does not explicitly name the sibling it complements at the queueing stage, so it falls just short of full differentiation.

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 concrete next steps conditioned on outcome: on succeeded, inspect result and call get_study; on failed, inspect the saved study before retrying. That is a clear usage contract, though it never says when not to poll or how often 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the meaningful scoping constraint that the study must be owned and of BYOP type, but it says nothing about behavior when the study is not a BYOP study, whether missing configuration returns empty or errors.

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 waste. The positive definition comes first and the disambiguation follows, which is exactly the right front-loading for a routing decision.

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 nonetheless enumerates the three returned artifacts. Annotations cover the safety profile. The only gap is error/edge-case behavior for non-BYOP or unconfigured studies, which is minor for a simple two-parameter read.

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 a UUID pattern. The description partially compensates by implying study_id must reference an owned BYOP study, which adds semantics beyond the bare UUID format. It adds nothing about organization_id or billing implications.

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 (external panel configuration: entry link, respondent ID parameters, outcome redirects) scoped to one owned BYOP study. It explicitly says what it is not (individual BYOP invitations, paid User Intuition Panel recruitment), though the closest siblings in the list — configure_external_panel and regenerate_external_panel_token — are not named.

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?

"For one owned BYOP study" implies the prerequisite context (ownership, BYOP study type) and the second sentence excludes two adjacent concepts. However, no explicit when-to-use vs. configure_external_panel, delete_external_panel, or regenerate_external_panel_token is given, so an agent must infer that this is the read-only counterpart to the configure/delete 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that the response may contain a status or an estimate depending on request state, which is genuinely useful beyond annotations, but permission requirements or behavior for unknown IDs is not mentioned.

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 short sentence with zero filler, front-loading the verb and resource. The trailing 'status or estimate' slightly muddies whether both are returned or one is conditional.

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 tool is a simple two-param read. Still, the description gives no guidance on how a not-found or pending request behaves, nor routes to the companion list tool.

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

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

Schema coverage is 50%: organization_id carries a description pointing to list_organizations, and request_id is well-typed as a UUID with format and pattern constraints. The description adds nothing about either parameter, so it neither helps nor hurts, making a baseline 3 appropriate.

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

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

States a specific verb and resource ('Get one feasibility request') and clarifies the returned payload includes status or estimate. The word 'one' distinguishes it from the sibling list_feasibility_requests, though the sibling is not named.

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 singular 'one' implies the tool is used when a specific request_id is already known, and the sibling list_feasibility_requests covers discovery. However, the description never states when to use this versus the list tool or cancel_feasibility_request, leaving the agent to infer.

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, so the safety profile is covered. The description adds genuine behavioral context beyond that: it discloses that the expected-finish projection is conditional ('when enough progress exists'), signaling a nullable/absent field, which helps the agent interpret 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 front-loaded sentence that opens with the verb and then lists the three returned metrics with no filler. It is dense but every clause corresponds to real output, though the packed triple-list is slightly harder to scan than a structured breakdown would be.

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 re-explained, and annotations cover safety. The remaining gap is routing: with many sibling read tools, the description does not tell the agent which adjacent tool answers a different question, leaving selection to inference.

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-schema (including a pointer to list_organizations), while study_id is undocumented but self-evident as the required UUID. The description contributes nothing about either parameter, which is acceptable but not value-adding at this coverage level.

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 fielding progress') and enumerates exactly what is returned: qualifying completions versus target, completed interview quality counts, and a rate-based expected finish. The purpose is unambiguous, but it never names or distinguishes itself from close siblings like get_study or 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?

There is no guidance on when to call this versus get_study or get_interview_usage_stats, nor any prerequisite or exclusion. The clause 'when enough progress exists' describes a data condition in the output, not a condition for choosing 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 establish read-only, idempotent, non-destructive behavior, and the description adds substantive traits beyond them: a 100-segment hard cap, an approximate 20 KB text bound, exclusion of system prompts/internal metadata, and preservation of turn ID and text_offset per segment.

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 that front-load the payload contents before the paging instruction; nearly every clause carries information, with the only waste being the mismatched next_message_offset label.

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 covers payload scope, size bounds, pagination, and content exclusions. Minor gaps remain around the offset field naming and error behavior for a bad interview_id.

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

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

Schema coverage is only 25% (just organization_id), so the description must compensate; it partially does by implying the 100-segment ceiling and offset-based paging, but it never explains message_limit vs message_offset explicitly and references a name (next_message_offset) that does not match the schema (message_offset).

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 uses a specific verb+resource and enumerates exactly what a single interview record returns: timing, stored format, configured study language, and transcript segments. It is clearly distinct from list_interviews and get_interview_usage_stats, though it never explicitly says so.

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 next_message_offset to fetch the next page" is a genuine pagination hint, but the schema parameter is named message_offset, and no guidance is given for when to prefer this over list_interviews or how to combine message_limit with the ~20 KB cap.

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 as a safe, idempotent read. The description adds meaningful behavior beyond annotations: eligibility excludes test interviews, omitted app/date values default to the backend app and a 30-day UTC range, and the applied scope is returned.

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 waste, and the core aggregation purpose is front-loaded. Default behavior is included only where it materially affects invocation.

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 and annotations covering the safety profile, the description supplies the remaining call-critical context: what is counted, default scope resolution, and confirmation that the response reports applied scope. No critical invocation information is missing.

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

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

Schema coverage is high at 80%, so most parameters are already documented. The description adds useful semantics for omitted app_id and date parameters by stating that the backend resolves the default app and a 30-day UTC range; cadence remains undocumented beyond its enum.

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 precise resources ("eligible non-test interview counts and billed units"), with date-range scoping. It clearly identifies a usage-statistics tool rather than interview CRUD or listing tools in the 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 purpose implies usage reporting, and the description explains default app/date resolution. However, it does not explicitly say when to use this instead of related tools like get_interview, list_interviews, or get_account, nor does it state exclusions.

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, so the safety profile is covered; the description adds the non-obvious behavioral caveat that panel respondents are not returned by this tool, which prevents a confusing empty/error result. It also flags that a personal interview link and reward state are exposed, which is useful sensitivity context.

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, front-loaded with what is read and what is returned, then the usage rule and the exclusion. No filler, and the most decision-relevant constraint (panel respondents excluded) is one short clause.

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 available the description needn't enumerate return structure, and annotations cover the safety profile; the description still supplies the use-case and the respondent-type exclusion. The only thin spot is that multi-organization context is left entirely to the schema field text.

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 described in the schema (billing scope, use list_organizations), while participant_id carries only format/pattern constraints. The description adds no syntax or selection guidance for either parameter, so the schema does most of the work and the description only implies that a single participant is addressed.

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 ("Read one BYOP invitation") plus the exact fields returned (status, interview link, interview count, reward state), which is far more informative than the bare name. It also draws the boundary with panel respondents, so an agent can tell this apart from list_participants and other read tools.

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 it to verify the participant before changing their email, deleting the invitation, or sending a reward" gives concrete trigger conditions that map onto the sibling mutations update_participant, delete_participant, and send_participant_reward. It stops short of naming those siblings explicitly or saying when not to call it (e.g., how to discover the ID in the first place).

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=false, so the safety profile is covered without help. The description adds polling semantics and the post-success handoff, but discloses nothing about job states, terminal failure, or partial results — meaningful gaps for a polling endpoint.

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

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

Two short sentences with zero padding, and the core action is front-loaded before the follow-up instruction. The terseness borders on under-specification, but no sentence 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-value documentation is not required. Still, for a polling tool the description omits the job's lifecycle states and what to do while pending or on failure, leaving the agent to infer the control flow.

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 carries its own guidance, but job_id has only format/pattern with no description. The description never mentions job_id, its provenance, or how to obtain one, so it fails to compensate for the undocumented 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?

The description uses a specific verb ('Poll') and resource ('participant batch'), making the async-job nature clear and distinguishing it from sibling readers like get_report_job or get_customize_study_job. The mismatch between 'job' in the name and 'batch' in the description is minor imprecision but doesn't obscure the purpose.

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 implies the call should be repeated ('Poll') and provides a concrete follow-up step ('list_participants for the study'), which is genuinely useful routing. However, it never states the upstream trigger (job_id presumably comes from create_participants) nor how to act on failure, so the when-to-use guidance stays 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral content by disclosing the state-machine outcome (a succeeded job yields result_url) and the implicit handoff. It omits what a pending or failed job returns, which is the main gap.

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, front-loaded with the action and followed by the next step. Nothing extraneous.

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 enumerated, and the description still highlights the one field that matters (result_url). For a polling tool, the missing piece is terminal-state handling — what to do when a job fails or never completes.

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% — organization_id is documented in-schema, while study_id and job_id carry only format/pattern hints. Those two are largely self-explanatory UUIDs, and the description adds no scoping or ownership semantics, so it neither compensates nor leaves a serious hole.

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 ('poll an asynchronous report request'), which clearly separates it from mutating siblings like generate_report. It names the follow-up sibling get_study_report, though it doesn't explicitly differentiate itself from the other job-polling siblings (get_report_slide_job, get_customize_study_job, get_participant_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?

The description gives clear usage context: call it to poll a pending job, and once the job succeeds, switch to get_study_report using result_url. It stops short of stating when polling is unnecessary (e.g. job already terminal) or what cadence/backoff to use.

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 readOnly/idempotent annotations, it discloses two genuinely useful behaviors: a succeeded job issues a fresh private download URL valid 15 minutes, and the export itself expires after seven days. It omits the status set (pending/running/failed) and what a non-succeeded job returns, which is the main remaining behavioral gap.

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, then the two expiry facts. No filler and nothing redundant.

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 and read-only annotations already cover return shape and safety, so the description only needed to add lifecycle context — which it does via the 15-minute URL and 7-day expiry. It falls short only on polling guidance and on documenting the two required UUID 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 description coverage is only 33% — job_id and study_id carry no descriptions, only UUID patterns — and the description adds nothing about them. "Poll an ... export" weakly implies job_id identifies the export job, but there is no guidance on study_id scoping or when organization_id is required.

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?

"Poll an editable PowerPoint export" gives a specific verb (poll) and resource (PowerPoint slide export job), which separates it from the broader get_report_job and from queue_report_slides. It doesn't name those siblings explicitly, so an agent must infer the boundary rather than read it.

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?

"Poll" implies this is called repeatedly after an asynchronous queue operation, and the sibling queue_report_slides is the plausible trigger. However, the description never states when to call it, how often, or why one would pick it over get_report_job or get_study_report — usage is only implied.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for the context it adds: authorization is re-checked on every read, audio eligibility requires a complete participant turn and an owned recording, and evidence carries canonical transcript locators. These are real constraints an agent would otherwise have to discover by failure.

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 the primary capability front-loaded and the operational caveats (pagination, authorization) following. No filler, though the compressed noun list requires re-reading and the `next_cursor` naming drift costs a little clarity.

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 annotations carry the safety profile. Combined with the description's disclosure of auth re-checks and audio-eligibility rules, an agent has enough to call this correctly, even if the exact view-to-content mapping needs a schema peek.

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 17% (only `organization_id` is documented), so the description must carry most of the burden. It partially compensates by enumerating the readable content types that correspond to `view` values, but never names the enum values, never explains `run_id` vs `session_id` vs `evidence_id` selection, and refers to a `next_cursor` field while the request parameter is actually called `after` — a terminology mismatch that could send an agent looking for a nonexistent argument.

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

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

Opens with a specific verb ('Read') and enumerates the resources available: run, verified claims, evidence, timed highlights, exports, source coverage, session history. This maps well onto most of the `view` enum. It does not differentiate itself from overlapping siblings such as `inspect_research_session`, `view_research_answer`, or `get_research_deliverable`, so an agent cannot resolve those collisions from the description alone.

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: the enumerated content types tell the agent this is the inspection surface for analysis output, and 'Follow next_cursor until exhausted' gives a concrete iteration instruction. There is no explicit when-to-use / when-not-to-use guidance and no naming of the sibling that handles raw session data or file downloads 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 say readOnly, idempotent, and non-destructive, so safety is covered. The description still adds real value: a succeeded job returns a FRESH private download_url, source access is rechecked at download time, and expired or revoked sources will fail. That is genuine behavioral context an agent cannot get from annotations or 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?

Three short sentences, front-loaded with the action and followed by the key return-value and access-constraint facts. Every sentence carries information; nothing is padding.

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

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

An output schema exists, so return-value detail is not strictly required, and the description usefully flags the download_url behavior. But for a polling tool it omits the essentials: what a pending or failed job yields, whether the caller should poll repeatedly, and the dependency on queue_research_deliverable for job_id. Adequate but with clear gaps.

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%, and the undocumented parameter is the required job_id, whose schema entry carries only format/pattern constraints. The description uses "job" but never says that job_id comes from queue_research_deliverable, nor does it mention organization_id or any hint about how these interact. 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 states a verb and target ("Poll a Hub export") and clarifies that a succeeded job yields a download_url, so the core action is graspable. However, "Hub export" is jargon that never names the deliverable or the research domain, and it does not distinguish this from sibling job-pollers such as get_report_job, get_customize_study_job, or get_participant_job. Purpose is implied rather than sharply 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?

There is no explicit when-to-use or when-not-to-use guidance. The description never links this to queue_research_deliverable (the tool that presumably produces job_id), nor does it contrast with download_research_output or cancel_research_deliverable. The agent must infer the polling workflow entirely from the name and the word "job".

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, so the bar is lower, yet the description still adds real behavioral context: approval must precede BYOP participant creation, approval is scoped by study_id + updated_at so it survives resumed workflows, and study_link is a live participant link that starts the participant experience rather than a preview. The only gap is that these are workflow obligations rather than properties of the call itself.

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 call ordering are front-loaded, which is good. But the paragraph then sprawls into launch-approval policy, BYOP approval caching, and a note that the public API exposes no researcher-preview URL – material that belongs to approve_panel_launch or launch_panel rather than a read tool, diluting the core 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?

With an output schema present, return fields needn't be enumerated, and the description still adds the one thing the schema can't convey: how to interpret dashboard_url versus study_link. For a 2-parameter read tool with full annotations, the definition is complete enough to call 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%: organization_id is described in the schema, while study_id carries no description. The description mentions retaining study_id, but only as workflow state, not as parameter semantics, and it never explains when organization_id should be supplied versus omitted. Baseline 3 is appropriate since the schema does part of the work.

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

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

The first sentence gives a specific verb and resource and enumerates the payload ('plan, audience targeting, screeners, and concept assets'), which distinguishes it from list_studies and from job-status siblings like get_customize_study_job. It also ties the resource to the sibling that mutates it (customize_study). It never explicitly contrasts itself with review_study or get_study_report, so it stops short of full sibling differentiation.

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

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

Explicit call-ordering guidance is given: 'Call before metadata updates and after customization to verify the result,' and it names the alternative channel for panel launch approval (launch_panel MCP App / human chat confirmation). What's missing is when NOT to reach for it – e.g., use list_studies when you have no study_id – leaving that inference to the agent.

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, so the safety profile is covered; the description adds genuinely useful behavior: the default is a *small* overview and 'included_sections' distinguishes omitted from empty sections. It also flags that findings may carry structured prevalence and source quotes 'when available,' warning of variable payload shape.

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

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

Four compact sentences, front-loading the default behavior before the enumeration of view options. Slightly dense with the inline parenthetical list, but every 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 prose; given that, the description covers the default mode, the selection mechanism, the empty-vs-omitted pitfall, and conditional content. Nothing essential to invoking it correctly is missing.

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

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

Schema coverage is only 33%, and the description correctly compensates by enumerating the meaningful 'view' values and contrasting section views with 'full', plus explaining 'included_sections' semantics that the schema does not. study_id and organization_id get no added detail, but organization_id is already documented in-schema and study_id is self-evident.

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 ... report overview' for a study) and immediately describes the default scope. It distinguishes itself from report-generation siblings by framing the output as a report read with selectable sections, though it never explicitly names get_study or generate_report as alternatives.

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

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

Gives clear guidance on when to use the default overview, when to pick a single section, and when to use 'full' — that is real when-to-use guidance for the main parameter. It stops short of naming sibling tools or stating when-not to use this (e.g., use get_study for metadata only).

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context by stating the signing secret is withheld from the response, which an agent would otherwise have to infer from the output schema.

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

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

A single short sentence with no filler, and the key qualifier (secret withheld) is front-loaded. It is arguably too terse rather than too long, which is not a conciseness defect but leaves gaps 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?

Annotations and an output schema carry most of the load, and the redaction note is a useful addition. Still missing is any guidance on choosing this over list_webhooks and any clarification of the organization_id scoping required for a correct call.

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 (including the list_organizations pointer) but webhook_id has only a format/pattern. The description adds nothing about either parameter, so it does not compensate for the undocumented UUID input.

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') and scopes it with 'by ID', which implicitly separates it from list_webhooks. It does not explicitly name a sibling alternative, but the ID-based single-resource fetch is unambiguous.

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

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

Usage is only implied: 'by ID' signals this is for when a webhook identifier is already known, and the sibling list_webhooks covers discovery. No explicit when-to-use or when-not-to-use statement, and no prerequisites such as organization scoping are given.

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 safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower and the description clears it by adding traits annotations cannot express: cursor passthrough semantics ('Follow next_cursor unchanged as after'), and job-state semantics ('Job success includes answer/references or output_id; partial remains explicit'). That tells the agent how to interpret a non-final result, which is genuinely useful behavioral context.

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 what-it-reads enumeration is front-loaded, and every subsequent clause (ID mapping, cursor rule, job-state note) carries distinct information. The phrasing is telegraphic to the point of awkwardness in places ('Follow next_cursor unchanged as after'), and the trailing editing hint is slightly orphaned, but nothing is padding.

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

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

With 7 parameters, an output schema present, and strong annotations, the description covers the pieces an agent cannot infer: the view-to-ID mapping, pagination continuation, and partial-job interpretation. Return-value shape is legitimately delegated to the output schema. The missing `limit` explanation is the one substantive hole for a paginated listing 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 14%, so the description must carry the burden — and it largely does: it defines which identifier each `view` requires and how `after` relates to the returned cursor. The gap is `limit`, which is never mentioned in the description and has no schema description either; an agent must infer its pagination role from the name alone. Against the low coverage baseline, this is above adequate but not exhaustive.

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 names a specific verb (Read) and enumerates the exact resource set: Hub sessions, one session, sources, chat history, a durable job, Studio outputs. That maps one-to-one onto the `view` enum, so an agent can tell this is the read-side counterpart to the create/delete/edit siblings. It stops short of naming any sibling explicitly, which keeps it out of 5 territory.

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 conditional routing within the tool (session_id for most views, job_id for job, output_id for output), which is real usage guidance, plus a workflow hint: 'Read the existing output before editing it.' But it never addresses when to use this versus adjacent readers like get_study, view_research_answer, or download_research_output, and never states exclusions or prerequisites beyond the ID mapping.

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, openWorldHint=true and idempotentHint=false, and the description adds real behavioral depth beyond those: the first call does not spend money, the second requires fresh human confirmation, and launch fails if the estimate no longer matches study/country/inputs/balance/price or has expired. It stops short of describing cancellation/reversibility or the cost implications of a paid launch.

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 preview/no-spend caveat are front-loaded, and each sentence carries distinct information about the approval flow, the nonce round-trip, and estimate validity. The fourth sentence is long and carries several instructions at once, but overall the length is proportionate to a high-stakes two-phase 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?

For a destructive, paid, 10-parameter tool with a 5-required-parameter gate, the description covers the critical path: preview, human approval, nonce return, and estimate-freshness failure. With an output schema present it need not describe return values, though the relationship to approve_panel_launch and any cancellation path remain unaddressed.

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; it does explain human_confirmed (must be true), the role of the returned chat_approval_nonce, and the consistency conditions behind estimate_id. It says nothing about target, frequency, organization_id, or study_id, leaving several undocumented parameters unexplained 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?

The description states a specific verb and resource ('launch' the 'review panel' for a saved study plan) and immediately explains the two-phase preview-then-spend behavior, so the purpose is unmistakable. It does not, however, differentiate itself from the close sibling approve_panel_launch or explicitly route agents from estimate_panel, so an agent must infer the boundary.

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 clear when-to-use guidance with alternatives: the first call previews without spending, App clients require an in-App Approve click, and non-App clients must round-trip through chat with chat_approval_nonce and human_confirmed=true. It also supplies an exclusion ('Never infer confirmation from a prior study or quote'), though it never names the near-identical sibling approve_panel_launch, leaving that choice ambiguous.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful behavioral details: newest-first ordering and bounded pagination, but it does not describe auth requirements, error conditions, or return characteristics beyond what annotations and the output schema provide.

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 wording. It efficiently conveys the core action, scope, ordering, and pagination behavior.

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

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

For a simple list tool with rich annotations and an output schema, the description covers purpose, ordering, and pagination adequately. It leaves parameter usage details to the schema, which is reasonable, though it could mention how it relates to get_feasibility_request.

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 should compensate for undocumented parameters. It mentions 'bounded pages' but does not explain page or page_size semantics, defaults, or limits; organization_id is documented separately 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?

The description states a specific verb and resource: list the account feasibility requests. It adds ordering and pagination details, making the scope clear, though it does not explicitly contrast with get_feasibility_request or other siblings.

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

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

The description gives no explicit guidance on when to use this tool versus get_feasibility_request or other alternatives. The listing purpose is implied, but there are no exclusions or 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 readOnlyHint, idempotentHint, closed-world, and non-destructive behavior. The description adds that rows are 'lightweight' and directs the agent to get_interview for full details, which is useful context about output scope beyond the annotations. It does not describe pagination behavior, but with page and page_size visible in the schema, the gap is minor.

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

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

Two short sentences, front-loaded with the core purpose. Every phrase earns its place: the first states what the tool does, the second provides actionable context for when to use a different tool. No boilerplate 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?

The output schema exists, so return values need not be explained. Annotations cover the safety profile. However, for a list tool with 7 filter parameters, the description does not explain what can be filtered or how the filters combine, leaving the agent to infer from bare schema names. It is minimally adequate but thin.

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

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

There are 7 parameters with only 14% schema description coverage (only organization_id has a description). The tool description mentions no parameters at all, so it does not compensate for the low coverage. The schema provides names, types, and enums, so an agent can infer some meaning, but no added semantics (e.g., how status or quality filters behave, or how pagination works) are given.

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 uses a specific verb ('List') and resource ('interview rows'), and adds the qualifier 'lightweight' to distinguish the output from full interview details. It implicitly contrasts with get_interview by saying 'Fetch an interview to get messages, recordings, and screener responses', giving an agent enough to tell the two apart. It does not explicitly differentiate from other list_* siblings, but the resource is clear.

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 implies when to use get_interview instead of this tool: when you need messages, recordings, or screener responses. However, there is no explicit guidance on when to use list_interviews versus other list tools like list_studies or list_participants, and no exclusions or prerequisites are stated. Usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond that: users can belong to multiple orgs, search spans org name, active owner name and owner email, and the response includes IDs and owner contacts.

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: purpose first, then search/return scope, then the required workflow step. The sentence about users belonging to multiple organizations earns its place by explaining why a list call is needed.

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

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

An output schema exists, so return values need not be detailed, yet the description still notes that IDs and owner contacts come back. The only meaningful omission is pagination guidance for page/page_size.

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%: search is documented in the schema and echoed in the description, and organization_id is implicitly explained by the 'supply organization_id on subsequent tools' line. The page and page_size parameters receive no explanation in either place, so the description only partially compensates.

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

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

States a specific verb and resource (list organizations) plus the access scope ('you can access') and the searchable fields, so the agent knows exactly what the call returns and how it can be narrowed. No sibling tool competes for this capability, so differentiation is inherent.

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 instructs the agent to ask the human which organization to use and to pass organization_id to subsequent tools, which is clear workflow guidance. It does not, however, mention when this is preferable to a sibling like get_account for org resolution.

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 openWorldHint=false, so safety is covered. The description adds genuinely non-obvious semantics: records are participations rather than deduplicated people, and panel/open-link respondents appear as anonymous interviews. It does not mention pagination defaults or sort order, but that is a minor gap.

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 with zero filler; the core output shape is stated first, then the identity caveat, then the routing alternative. Every sentence adds information an agent would otherwise have to guess.

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 two things that matter most here: what a record represents and which sibling to use for sessions. The only missing piece is any guidance on the filtering and paging 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 description coverage is only 33%, and the description mentions no parameters at all — not the email/study_id/external_id filters, not page/page_size. Only external_id and organization_id carry any schema prose, leaving the majority of the six parameters undocumented in either place.

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

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

States a specific verb and resource ('List BYOP invitation records') and immediately clarifies what each row contains: personal interview link, status, visible interview count. It also pre-empts the most likely misreading by saying these are participations, not deduplicated people, which separates it cleanly from list_interviews.

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 routes the agent to list_interviews(participant_id) when it wants interview sessions rather than invitation records, including the argument to pass. It gives clear usage context but does not address when to prefer get_participant or create_participants, so it stops short of full alternatives coverage.

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