Minds: Synthetic Market Research Panels

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

The description discloses key behaviors beyond annotations: it creates a private Study, starts asynchronous responses, returns the Study identifier and links, may reformulate the question, and refuses to start if an asset cannot be read. There is no contradiction with the annotations.

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

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

The description is front-loaded with the core action and uses subsequent sentences for routing, behavioral caveats, and file constraints. It is somewhat redundant with the schema's repeated local-file:// warnings, which keeps it from being maximally concise.

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

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

Despite having no output schema, the description states what is returned: the Study identifier and links. It covers async behavior, reformulation risk, the multi-question exclusion, and asset accessibility requirements, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra operational meaning: the question field content can reach Minds and should not contain planner-only instructions, audience resolution can be exact ID or fuzzy name, and attachment URLs must be fetchable rather than local paths. This goes beyond the schema descriptions.

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 precise verb and resource: submits exactly one respondent-visible standalone question to one existing Audience by ID or fuzzy name. It clearly distinguishes this from multi-question Study creation and from sibling tools by explicitly forbidding questionnaire, battery, or section use cases.

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

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

It gives explicit when-to-use criteria: exactly one standalone question to one Audience. It also provides a direct alternative: create a Study and plan the complete multi-question block instead. File URL constraints and the no-local-file:// rule give practical invocation guidance.

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

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

Despite useful annotations (idempotentHint, openWorldHint, destructiveHint=false), the description carries substantial extra behavioral weight: automatic classification may reformulate the question so verbatim wording is not promised, the returned status is authoritative (queued/running means actually submitted, planning_required means declined with nothing submitted), and the planning_required payload is described. It also warns the full question value reaches respondents and that MCP cannot read local file:// paths. This far exceeds what the annotations convey.

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

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

The core purpose is front-loaded and essentially every sentence carries decision-relevant content, but the description is verbose. The file:// limitation is stated in the description and then repeated three more times across schema attachment properties, and the 'never use for multi-question' exclusion is restated multiple times. It is substantive, not bloated, but could be tightened by roughly a third without losing information.

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

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

For a 14-parameter tool with no output schema, the description compensates well: it defines the three possible status outcomes and what planning_required returns, explains classification/reformulation risk, and clarifies file URL constraints and durable storage import. Minor gaps remain—the response shape is only partially described ('status and workspace links'), and active-session continuation semantics live only in the schema—but nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3 with the schema doing the heavy lifting. The description adds value beyond the schema for the question parameter by explaining the system may classify or reformat it and that any text can reach Minds, and it reinforces attachment URL constraints. This lifts it above baseline, though the description does not systematically walk through each 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 opens with a precise verb+resource+scope: 'Submits exactly ONE respondent-visible question in an existing Study.' This is immediately distinguishable from siblings like plan_study_questions, run_study_questions, and create_study because it scopes to a single question inside an existing Study and explicitly says it does not create or enumerate Studies.

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 provides explicit applicability ('one standalone question, or one adaptive follow-up whose wording could not be known before earlier results') and an explicit exclusion: never for questionnaires, surveys, batteries, sections, cohesive question sets, or two or more known questions. It also names the correct alternative routing—the complete known set belongs in 'one planned and confirmed multi-question block'—so an agent knows exactly when to choose a different 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?

The description substantially augments the annotations: it states idempotency ('is idempotent for identical inputs'), the privacy default ('keeps the Audience private unless link sharing is enabled' plus the explicit 'Do not enable it to be helpful' warning), silent downgrade behavior ('the server SILENTLY downgrades to balanced'), specific refusal codes (403 MODE_CAP, 403 PLAN_LIMIT), background training semantics, and the 'never created at a partial size' guarantee. No contradictions with readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=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?

The main description is a single dense, semicolon-heavy sentence — every clause earns its place and the core purpose is front-loaded. Parameter descriptions are verbose but each adds non-obvious operational detail. The density is justified for a 16-parameter tool, though splitting the lead sentence would improve scannability.

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 16-parameter, 0-required-param tool with no output schema, this is remarkably complete: it documents refusals, plan downgrades, the preview-then-create flow, background training polling (GET /api/v1/minds/{id}/training), file URL constraints, and output locations via structuredContent references. No significant gap for an agent to select and invoke it correctly.

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

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

With 100% schema description coverage the baseline is 3, but the parameter docs add substantial operational meaning: memberCount explains the two refusal codes and the 6000 system ceiling vs. plan allowance, trainMembers explains the ~40-Mind bulk-creation default and queued training pipeline, isLinkSharingEnabled warns about world-readable publication, and files explains that local file:// paths are unreadable. This is far beyond schema-type documentation.

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 — 'Creates a grounded Audience of synthetic Minds from a population or audience brief' — and enumerates distinct capabilities (web research, provenance audits, sizing modes, background training, idempotency, privacy default). The title reinforces the purpose, and the resource (Audience creation) cleanly separates it from study-oriented siblings like create_study and ask_audience.

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 top-level description doesn't name sibling alternatives, but parameter docs embed strong workflow guidance: 'Call get_audience_limits for the real one' (memberCount), the groundingPreview two-call pattern ('Present the axes to the user for approval, then call again without groundingPreview'), and datasetSegmentation's requirement that audienceCreationMode="benchmark_depth". This provides clear when/how context, though it doesn't explicitly exclude sibling tools.

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

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

The description adds meaningful behavioral context beyond the annotations: composite creation is atomic and rolls back partial Audience failures, Studies are private by default, and enabling link sharing publishes attached Audiences and Minds. These are non-obvious side effects an agent needs to know. No contradiction with the annotations.

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

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

The core action is front-loaded, and every sentence contributes usage or behavioral guidance. The enumeration 'questionnaire, survey, battery, section, cohesive question set, or request with two or more known questions' is somewhat verbose but not 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?

Combined with the rich schema and annotations, the description gives an agent enough to use the tool correctly: creation sources, multi-question workflow rules, atomicity, and privacy side effects. The only modest gap is that no output or return value is described, though no output schema exists.

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

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

Schema description coverage is 100%, and the schema already documents each parameter, preferred vs legacy aliases, defaults, and the sharing side effect in detail. The description only reinforces the conceptual split between existing Audiences and inline configurations without adding new parameter-level semantics, so the baseline score of 3 is appropriate.

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

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

The description states a specific action and resource: 'Creates a new Study workspace from existing Audiences or inline Audience configurations.' It also explicitly distinguishes itself by noting it 'does not ask questions or run research,' which separates it from sibling tools like ask_study and ask_audience.

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 provides clear when-to-use and when-not-to-use guidance: follow-up research does not require another Study, multi-question sets must not be submitted as separate direct questions, and a direct question is appropriate only for a standalone or dependent next question. This is actionable routing guidance beyond simple 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?

The description adds value beyond the annotations by disclosing that output uses the unified branded renderer, supports specific formats, and returns binary artifacts as base64. This is especially helpful because there is no output schema. It does not contradict the idempotentHint or destructiveHint annotations.

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

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

Three sentences, no filler, with the key action and resource front-loaded. The format list and base64 return behavior each earn their place.

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

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

Given the rich parameter schema and idempotent annotation, the description covers the essential outcomes: what is exported, supported formats, and return encoding. It lacks explicit prose about cached-artifact behavior or identifier selection, but the force parameter and schema descriptions cover those gaps. Without an output schema, the base64 statement is essential and present.

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

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

Schema description coverage is 100%, so the schema already documents all parameters and aliases. The description adds no parameter-specific meaning beyond naming the export formats, which the schema already enumerates. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Exports') and resource ('an Audience brief'), which clearly distinguishes it from sibling tools like export_study, export_heatmap, and export_mind. The target resource is unambiguous.

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

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

The description implies the tool is for exporting audience briefs, but it does not explicitly state when to use it over the other export siblings or provide any when-not guidance. Sibling differentiation is left to inference from the tool name and the word 'Audience brief'.

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 idempotency and non-destructiveness. The description adds useful behavioral context by specifying the exact return artifact: the same ZIP archive as the web app, containing a PDF report, Markdown, images, and metadata. This goes beyond the structured annotations and does not contradict them.

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

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

Two tightly written sentences with no filler. The first sentence front-loads the action and key identifier; the second specifies the output contents. Every clause contributes meaningful information.

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

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

For a tool with a single required parameter and full schema coverage for optional parameters, the description provides everything needed to call it correctly: what is exported, where the identifier comes from, and what the returned artifact contains. The absence of an output schema is mitigated by the explicit description of the ZIP contents.

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

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

The input schema has 100% description coverage for all six parameters, so the description is not required to explain parameter semantics. The description only reinforces messageId's role as the completed-result identifier, adding no information beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Exports') and clearly identifies the resource ('website heatmap') and source ('from a Study result' with 'message ID'). This differentiates it from sibling export tools like export_audience, export_mind, and export_study by resource type.

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 a clear usage condition: export only a completed website heatmap identified by the message ID reported with the completed result. It does not explicitly name alternatives or exclusions, but the resource-specific wording makes the intended context unambiguous.

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

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

The description adds behavior beyond annotations by explaining the default return mode (inline Markdown) and the binary artifact behavior (base64 plus workspace link). Since annotations already indicate idempotence and non-destructiveness, this focused extra context is valuable.

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, tightly written, front-loading the core action and then adding the return format distinction. No filler or redundant repetition of the title.

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

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

Given no output schema, the description still provides enough: what is generated, how to identify the target, supported formats, and the return mode for each format. A complete call is derivable without additional assumptions.

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

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

The schema covers all 4 parameters with descriptions, so the baseline is solid. The description adds useful context on how formats behave and clarifies that both exact ID and fuzzy name are valid identifiers, which helps an agent select the right operationally.

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: 'Generates a branded profile for one existing Mind.' It clearly distinguishes itself from sibling export tools (export_group, export_panel, export_heatmap) by naming the target resource and the identifier mechanism.

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 context: use this when exporting a profile for an existing Mind, identified by exact ID or fuzzy name. It does not explicitly name sibling export tools as alternatives, but the intended scope is unmistakable.

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 idempotence and non-destructiveness, so the description's added value is its clarification that exports are asynchronous and yield a job ID. This is behavior beyond the structured annotations and helps an agent know not to expect the artifact in the immediate response. Some context, such as how to retrieve completion status, is left implicit but is not critical for 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?

The description is two focused, front-loaded sentences: it immediately conveys the asynchronous behavior and return value before listing supported outputs. No filler or redundant explanation.

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 tool with 9 parameters but comprehensive schema descriptions, the description gives enough high-level orientation around purpose, formats, and the job-ID return. It lacks only minor operational detail such as how to poll the eventual export status, but the return contract is explicit and the remaining complexity is handled by 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?

The input schema has 100% parameter description coverage, so the schema already explains every parameter thoroughly. The description's format summary is helpful orientation but doesn't add significant semantic meaning beyond the schema. The 3 baseline is appropriate because the schema carries the semantic load.

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 action and resource ('starts an asynchronous export of Study results') and clearly separates this from sibling exporters like export_audience, export_heatmap, and export_mind by scoping it to Study results. It also states what the caller receives: an export job ID.

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

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

The description gives clear context for when to call it: when exporting Study results asynchronously, in one of several listed formats. It does not explicitly name sibling tools or say when not to use them, but the resource scope and format list are enough to route an agent correctly in most 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 mark this as read-only and idempotent, and the description adds substantial behavioral context beyond that: it distinguishes automaticSizingCeiling from explicitCountCeiling, explains that only 'balanced' mode has the explicit ceiling, and discloses the MODE_CAP refusal behavior and the fallback to memberCap. This goes far beyond what the annotations 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 front-loaded with a bold, actionable directive, followed by precise, non-redundant details about the returned ceilings and failure behavior. Every sentence earns its place, and the warning about expensive mid-creation failures justifies the tool's importance without fluff.

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

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

For a read-only, optional-parameter tool, the description fully covers when to call it, what it returns, how the mode parameter alters behavior, and what error occurs on exceeding a ceiling. Even without an output schema, it enumerates the key returned fields and their semantics, leaving no critical gap for an agent deciding to invoke this 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?

The schema documents the optional mode parameter at 100% coverage, and the description adds meaning by explaining what each mode ceiling represents and how mode choice affects which ceiling applies. It clarifies the consequences of omitting memberCount and of stating a size, making the mode parameter semantically richer than the schema alone.

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

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

The description uses a specific verb and resource ('returns the ceilings that apply to THIS account') and clearly frames the tool as a pre-creation check for Audience sizes. It distinguishes itself from creation and listing siblings by emphasizing that it reports limits rather than creating or listing anything.

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

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

It gives explicit when-to-use triggers: 'Call this before creating an Audience whenever a size is in play', with concrete examples like a named number, 'as many as possible', or choosing a creation mode. It also actively recommends the tool over guessing, explaining the cost of being refused mid-creation.

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 readOnly, idempotent, and non-destructive behavior. The description adds substantial context beyond annotations by detailing the exact contents of the response (immutable plan, execution plan, question audit, progress, artifacts, deterministic calculations, stage readiness). This is especially valuable given there is no output schema.

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

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

The core result is front-loaded in the first clause, and the long enumeration of response components is information-dense rather than redundant. It is a single well-structured sentence, though slightly long due to the itemized list.

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

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

With no output schema, the description compensates by enumerating the returned artifacts and noting durability. It also clarifies the run is inside a Study and confirmed, which helps set expectations. It does not mention error cases or how to choose among the five optional identifiers, but the schema covers the identifiers fully.

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

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

Schema description coverage is 100%, and each parameter has a clear explanatory description, including which is preferred (runId) and which are legacy aliases. The description adds no new parameter-level meaning; baseline 3 applies when schema carries the full burden.

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?

Description uses a specific verb ('Returns') and a specific resource ('progress or results for one confirmed multi-question run inside a Study'), followed by a precise enumeration of returned components. This clearly distinguishes it from sibling tools like get_study_status and get_study_summary that operate at the study level rather than the run level.

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 'one confirmed multi-question run' implies this is called after a run has been created, giving clear context. However, it does not explicitly state when not to use it or name alternatives such as get_study_status, so it stops short of full exclusion guidance.

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

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds meaningful nuance: values may be numeric answers or classified labels, message fields contain original Mind responses when available, and locale is only the display locale, not a language guarantee. These go beyond the annotations.

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

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

Three sentences with no filler: the first is front-loaded with the primary return resource and its major categories, the second clarifies value semantics, and the third adds an important locale caveat. Every sentence earns its place and no schema content is redundantly repeated.

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

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

For a read-only status tool with no output schema, the description inventories the main return categories and clarifies ambiguous fields (values, message, locale). It does not specify the exact export job states or response shape, but the annotations and detailed parameter schema make the description sufficient for selection and 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 100% and each parameter is already documented in detail, including legacy field names, UUID formats, defaults, and omission rules for the active Study. The description adds only the general notion that export identifiers trigger job-status mode, which the schema already supports for the individual parameters. This meets the baseline but does not materially extend 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 opens with a specific verb ('Returns') and names the resource ('current Study state'), then enumerates distinct facets: live progress, completed per-Audience results, linked Minds, Study links, and export job status. This clearly distinguishes it from siblings like get_study_summary or get_study_run, and the export-polling mode is explicitly identified.

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 context for when the tool applies: querying overall study state, and specifically polling an asynchronous export when export identifiers are supplied. It does not explicitly name alternatives or state when not to use it, but the trigger condition for the export-job mode is stated clearly.

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 convey idempotency, non-read-only behavior, and non-destructiveness. The description adds that the tool can 'refresh' a summary rather than only reading it, and that output retains heatmap-compatible metadata, but it does not discuss side effects, rate limits, or what regeneration entails.

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 two sentences with no filler. The primary action and output format are front-loaded, and the second sentence adds relevant, non-redundant detail about metadata retention.

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 gives a solid high-level picture of the return format and refresh behavior, but lacks detail about what 'flexible evidence blocks' means and does not situate the tool among related siblings. Given no output schema and a 7-parameter surface, the description is adequate but leaves 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?

Schema description coverage is high at 86%, with detailed parameter descriptions for force, length, refresh, and Study identifiers. The tool description itself adds no parameter-specific semantics, so the baseline score of 3 applies.

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

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

The description uses a specific verb ('Returns or refreshes') with a clear resource ('semantic summary for a Study') and output format ('Markdown plus flexible evidence blocks'). It is distinct from sibling tools like get_study_run and get_study_status, which target run state and status rather than the semantic summary.

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 about when to use this tool versus alternatives such as get_study_run, get_study_status, or export_study. Some context about active Study selection exists in parameter descriptions, but the tool description itself does not provide usage direction 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?

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds value by disclosing the composition of returned lists (member Minds, sharing state, links) and the fuzzy-search capability, which are not captured by annotations.

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

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

Two sentences, no filler; the primary action and the optional parameter are front-loaded. Every clause adds 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 tool is simple (one optional param, read-only, no output schema), and the description covers the main output facets and search behavior. It does not mention pagination or empty-result behavior, but these are minor for a straightforward list tool.

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

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

Schema description coverage is 100% for the single searchQuery parameter, and the description largely restates the schema's fuzzy-name-search semantics. It adds 'optional' but no new meaning beyond the schema, so baseline 3 applies.

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

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

States a clear verb ('Lists') and resource ('the authenticated user's Audiences'), and adds specific content details (member Minds, sharing state, links) that distinguish it from sibling list tools like list_studies. The optional fuzzy search is also noted. This is a specific, non-tautological definition.

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

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

The description implies the tool is for browsing the user's audiences and offers an optional search, but it does not explicitly state when to prefer this over alternatives such as ask_audience or export_audience. No exclusions or alternative routing are provided, so an agent must infer usage from the resource name.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds meaningful behavioral detail: availability is dynamic and only entries with executable:true can actually run. It also mentions fallback metadata, which is useful beyond the structured annotation info.

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-load the main purpose and immediately clarify the executable-versus-planned distinction. Every clause contributes meaning; no redundancy or filler.

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

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

This is a straightforward read-only list tool with one optional parameter, and the description covers the primary output fields. There is no output schema, so the description's list of availability, complexity, executable status, and fallback metadata provides enough context for an agent to understand what it will receive without over-explaining.

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

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

Schema description coverage is 100% and the includePlanned parameter is well-explained in the schema itself. The tool description does not add any additional parameter-specific meaning, so this stays at the baseline 3.

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 ('Lists Minds research methods') and clearly states the key reported attributes: availability, complexity, executable status, and fallback metadata. It also distinguishes the distinction between executable and planned methods, which separates it from sibling list tools like list_groups and list_panels.

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 context on when this tool is useful—when you need to know which research methods are executable versus experimental/planned. The parameter description reinforces this by saying the model can 'explain framework compatibility,' but no explicit alternative tools or exclusions are mentioned.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description does not need to restate safety. It adds useful behavioral context: the scope is limited to the authenticated user's Studies, and it specifies which fields are returned and that name search is fuzzy. It does not contradict annotations.

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

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

Two sentences, front-loaded with the operation and resource, followed by a crisp definition of a Study. No filler or redundancy; every clause adds information.

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

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

For a simple read-only list operation with one optional parameter and no output schema, the description covers scope, returned fields, filtering, and the domain concept. Nothing essential for calling the tool correctly is missing.

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

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

The single parameter searchQuery is already fully described in the schema (fuzzy matching by Study name); the description essentially repeats 'optional fuzzy name search'. With 100% schema coverage, no additional parameter semantics are needed.

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 ('Lists'), a clear resource ('the authenticated user's Studies'), and enumerates the included fields (Audiences, Minds, status, sharing state, links). This makes the tool's purpose unambiguous and distinguishes it from resource-specific siblings like list_audiences and list_study_drafts.

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

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

The description implies when to use the tool: when you need a user's Studies along with their associated data and optional fuzzy name search. However, it gives no explicit guidance about when to prefer list_study_drafts, list_audiences, or other sibling tools, and mentions no 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, and non-destructive behavior, so the description builds on that by adding that it covers durable unfinished drafts and returns the complete saved planning state for an exact ID. No contradiction is present, and the additional context is useful for invocation.

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 deliver the core function and key distinction with no filler. The most important usage distinction is front-loaded before the clarifying sentence about draft records.

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 tool with a single optional parameter and read-only annotations, the description covers what it lists, what it retrieves by ID, and how drafts relate to other study statuses. The absence of an output schema means return format details are not fully specified, but the description gives enough context for effective selection and use.

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

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

The schema already fully documents the optional draftId with 100% coverage, so the baseline is 3. The description adds meaningful operational meaning beyond the schema by linking draftId omission to listing and draftId presence to returning saved planning state.

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 precise verb and resource: listing durable unfinished study drafts or retrieving a complete saved planning state for one draft ID. It also explicitly distinguishes draft records from running or completed studies, which differentiates the tool from planning/run 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 clear context by describing both operating modes and noting that drafts are separate from running or completed studies. It implies when to use this tool for resumable drafts rather than active studies, though it does not explicitly name alternative sibling tools or provide direct when-not-to-use guidance.

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

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

Annotations are thin (only readOnlyHint=false, destructiveHint=false), so the description carries the burden and delivers: it affirms mutation yet non-execution, discloses the planner-bypass for fixed instruments ('the planner is then bypassed and the draft is an exact transcription'), and states hard asset constraints (no file:// read/upload, durable storage import, 'The Study refuses to start if Minds cannot read the asset'). No contradiction with the annotations; the non-destructive draft semantics align with destructiveHint=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?

Roughly 220 words for a 17-parameter, dual-mode tool, and nearly every sentence earns its place: applicability, exclusions, draft contents, non-execution, fixed-instrument path, and asset constraints. It is front-loaded with the core purpose. Minor redundancy: the file:// constraint is repeated extensively in the schema and could be trimmed in the description.

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

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

For a tool with two mutually exclusive modes, 17 parameters, attachment workflows, and no output schema, the description covers the critical operational facts: what the draft records (intent, stimuli, questions, response formats, locale, method, outputs, confirmation questions, revision metadata), that it doesn't execute, and the asset-readability precondition. Minor gap: the confirmation-question → answers → revision loop (draftPlanId/revision) is only implied, not spelled out as a workflow.

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

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

Schema description coverage is 100%, so the schema already documents all 17 parameters; the baseline is 3. The description adds genuine cross-parameter decision guidance beyond the schema: choose questions instead of request for fixed instruments, include every known question in ONE request, and never split known sets into per-question drafts. That lifts it above baseline.

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

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

States a specific action (creates or revises a non-executing draft), the resource (multi-question plan inside an existing Study), and the key constraint (non-executing). It also pins the scope precisely as the setup operation for every multi-question request, even when the user doesn't say 'study.' The phrase 'It does not start research' and 'non-executing draft' clearly separate it from execution-oriented siblings like run_study_questions.

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 applicability ('setup operation for every questionnaire, survey, battery, section, cohesive question set'), explicit exclusions ('A one-question draft is valid only for genuinely standalone research'), and a hard never-rule ('Never split a known set across one-question drafts or sequential runs'). It also routes to the alternative execution path ('execute them later as one confirmed run inside the Study') and to the fixed-instrument mode via the questions parameter instead of request.

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

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

Annotations already indicate a non-read-only, idempotent operation, and the description adds substantial behavioral context: server-side validation of revision, method availability, runner configuration, reviewed capabilities, consent, and idempotency key; refusal of the entire run when source material is unreadable; and the MCP file:// limitation. No contradiction with annotations.

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

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

The description is dense but purposeful, with each sentence contributing operational guidance: single-run behavior, confirmation requirement, server validations, file:// constraint, and readability refusal. It loses one point for mild redundancy about explicit confirmation and a long validator list that could be slightly tightened.

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 11-parameter, high-stakes execution tool with no output schema, the description covers the essential preconditions, failure modes, and invocation constraints: confirmation, monolithic execution, idempotency, advanced-method opt-in, file path limitations, and source-material accessibility. Combined with the detailed schema, an agent has sufficient context to call it correctly.

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

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

Schema description coverage is 100%, so every parameter is already documented in detail. The description reinforces the confirmation gate, idempotency key role, and advanced-method consent, but it does not add significant meaning for individual parameters beyond what the schema already provides.

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

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

The description clearly states that this tool 'Executes the exact stored multi-question draft revision inside the target Study after explicit confirmation.' It also clarifies the critical distinction from fragmented usage: one execution submits the entire draft as one durable run, not per-question or per-module runs.

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

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

The description explicitly says this operation is valid only after explicit confirmation, and gives a clear 'never' instruction against executing questions separately or creating per-module runs. However, it does not name alternative sibling tools, such as plan_study_questions or get_study_run, so routing guidance is present but not fully complete.

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 are all negative signals (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description carries the full behavioral burden. It discloses two non-obvious traits: revisions require the exact draftId plus expectedRevision pairing, and stale writes are rejected — a concurrency guarantee that materially changes how an agent must invoke an update. This is exactly the kind of context annotations cannot express.

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

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

Three sentences with zero filler: scope, persisted state, and concurrency rule each earn their place, and the primary purpose is front-loaded in the first clause. The ~48-word length is appropriate because the schema already carries parameter-level detail, so the description does not repeat it.

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 mutating tool with zero required parameters and no output schema, the definition thoroughly covers the invocation contract: what state is saved, how revisions behave, and when it does not apply. The one gap is the return contract — it never states that a create returns a draftId, which a downstream workflow would need for later revisions or a subsequent create_study call, so the agent must infer it.

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

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

Schema coverage is 100% with rich per-parameter descriptions (e.g., groupIds is a 'Legacy alias for audienceIds', methodId defers to list_research_methods), establishing a baseline of 3. The description adds framing on top: it groups the 13 parameters into a coherent persisted state bundle and reinforces the draftId/expectedRevision dependency that underlies the stale-write guard.

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-resource pair — "Creates or checkpoints an unfinished Quick or Custom Study draft" — and delimits scope with "without starting research," which distinguishes it from the create_study sibling. The sentence enumerating exactly what gets saved (objective, Audiences, method, questions, sources, planner step) further pins down what the tool owns.

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 establishes clear context: this tool persists incomplete planner state for later restoration, and "without starting research" signals a when-not condition. It stops short of naming the explicit alternatives (create_study for launching a study, list_study_drafts for reading drafts), so routing to siblings relies on inference rather than an explicit when-to-use/when-not-to-use statement.

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