Minds: Synthetic Market Research

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true), the description discloses that classification may reformulate the question, that the accepted task plus answer contract are returned with the original request retained, that ambiguous requests return planning_required before execution, and that the Study refuses to start if Minds cannot read an attachment. This is rich behavioral context an agent could not infer from the annotations alone.

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 front-loaded with the core action, then layers scope exclusions and attachment constraints. Every sentence carries information, though the attachment sentence partially duplicates the schema's lengthy attachment prose, making the block slightly heavier than strictly necessary.

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 mutation tool with nested params and an output schema, the description covers routing, the planning_required fallback, attachment fetchability constraints, and Study-refusal behavior — everything an agent needs to call it correctly without the output schema needing description-side explanation of 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 description coverage is 100%, so the schema already documents audience, question, attachments, and name in detail; the description largely parallels it. It adds only marginal framing, such as the note that numbered answer options do not by themselves constitute a battery, so the baseline 3 applies.

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

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

The opening sentence states a precise verb+resource+scope: 'Asks exactly one standalone question of one existing Audience,' then enumerates the side effects (private Study, async answers, returns Study id and links). This cleanly distinguishes it from siblings like ask_study, run_study_questions, and plan_study_questions that operate on full question sets.

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

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

It gives an explicit negative boundary — 'Out of scope: a questionnaire, battery, section or any request with two or more known questions' — and routes that case to a 'planned multi-question block inside a Study,' which implicitly names the sibling alternative. It stops short of naming ask_study directly, but the when-to-use and when-not-to-use conditions are both clear.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false). The description adds genuinely new context: the question text reaches the Minds and must exclude orchestration notes, classification of question types is automatic, and the result carries question id/status/workspace links. It does not, however, discuss execution cost or failure modes.

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

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

Three short paragraphs, front-loaded with the core action and then the out-of-scope rule. Dense but each sentence carries a distinct constraint; the caution about what may appear in question text is restated twice between description and schema.

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

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

For a six-parameter tool with an output schema and heavy annotation coverage, the description covers scope, exclusions, behavioral constraints on the question payload, and a hint at return contents. Nothing an agent needs to call 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 100%, so every parameter including the nested model/study/evidence/response objects is already documented. The description restates the 'one question only' constraint on the question field, which the schema also states, adding little beyond the baseline.

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

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

States a specific verb and resource ('Submits exactly one respondent-visible question in an existing Study') with an explicit scope boundary, immediately distinguishing it from the batch/questionnaire siblings like plan_study_questions and 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?

The 'Out of scope' paragraph names the exact condition that disqualifies this tool (two or more known questions) and routes that case to a planned multi-question block submitted once — a clear when-not rule with an alternative.

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

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

Annotations only declare readOnly=false, destructive=false, idempotent=true, openWorld=true. The description goes well beyond: creation is asynchronous and returns an operation to poll, previews consume no generation allowance and materialize no Minds, mismatched checksums fail closed before materialization, and the Audience is private unless link sharing is explicitly enabled. It also notes refusals (MODE_CAP, PLAN_LIMIT, no-evidence refusal) and the silent downgrade of deeper modes on non-enterprise plans.

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 mostly information-dense, with each clause carrying a distinct mode or constraint. It is long and overlaps noticeably with the already-verbose schema descriptions, so some of paragraph two is redundant rather than additive.

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 no explanation, and the description still covers the async lifecycle, how to resume via operationId, and the privacy default. For an 8-parameter tool with nested objects and multiple creation modes, nothing an agent needs to call 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 100%, so the baseline is 3, but the description adds cross-parameter composition semantics: the preview-then-commit sequence (pass reviewed snapshot back unchanged with its checksum), the trade-off between draft.preview and grounding.preview, and why composition.memberCount should be passed when a size is stated. This sequencing value is not derivable from any single parameter description.

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 an Audience from a free-text brief') plus the mechanism: the server researches the population, derives dimensions, and builds Minds with explicit profiles and exact segment allocation. It also differentiates from siblings by routing to the Audience-limits operation for ceilings and to import_audience_sources for file contents.

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 for every mode: new briefs default to the draft workflow, rework uses draft.preview=true with id/sha256, final creation uses draft.preview=false only after user acceptance, grounding.preview is called out as quota-only review, and direct creation via grounding.preview=false is flagged as the explicitly-requested exception. Alternatives (import_audience_sources, app upload for PDFs/images, get_audience_limits) are named with the conditions that select them.

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 far beyond the annotations by disclosing atomic rollback of partial Audience failures, always-creates-new semantics, byte-identical replay behavior with 'replayed: true', permanent no-delete consequences, and link-sharing side effects that publish Audiences and Minds. This rich context helps an agent anticipate side effects that readOnly/destructive hints alone would not convey.

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

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

Dense but every sentence earns its place: core action first, exclusions second, idempotency and irreversible consequences next, then atomicity and privacy. The front-loading of 'does not ask questions or run research' prevents immediate misuse.

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 all high-stakes aspects an agent needs before calling: idempotency, failure semantics, inability to delete, Audience immutability after creation, multi-question routing, and public-sharing side effects. With an output schema present, the absence of return-format detail is not a 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 100%, so each parameter is already documented in the schema. The description adds behavioral context (prefer audienceIds, don't enable link sharing unless explicitly requested) but does not need to restate parameter meanings, so the 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 names a specific verb and resource ('Creates a Study workspace') and immediately differentiates from siblings by stating it does not ask questions or run research. This makes it easy for an agent to distinguish create_study from ask_study and 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?

Explicitly states when not to use: follow-up research inside an existing Study needs no new Study, and two or more known questions belong in a multi-question block instead of separate direct questions. It also gives prerequisites: settle the Audience set before calling because Audiences cannot be added later and duplicates are permanent.

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 destructiveHint=true, but the description adds meaningful detail: deletion is permanent, the stored configuration is gone, and existing Studies and drafts survive. It also discloses the ownership restriction, going well beyond what the annotation alone conveys.

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 core action is front-loaded, and each sentence adds a distinct piece of useful context: permanence, side effects on derived resources, and ownership constraints.

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

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

For a one-parameter destructive operation with an output schema, the description is complete. It covers what is deleted, what is not affected, and who is allowed to delete, leaving no important ambiguity.

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 already documents templateId with 100% coverage, including that it is the template to delete permanently and owner-only. The description does not add new param-specific detail, 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?

The description states a specific verb and resource: permanently deletes a saved Study template owned by the authenticated user. It clearly distinguishes this from management or listing operations, even without naming a 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?

The description gives clear contextual guidance: only the owner's templates can be deleted)Skip, and shared-access teammates cannot delete templates they do not own. It also clarifies that existing studies and drafts are unaffected, which helps an agent reason about when this action is appropriate. It does not explicitly contrast with sibling alternatives, but the ownership and side-effect information is sufficient for basic 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 provide readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds useful behavioral context: it uses the same renderer as the web app and returns binary artifacts as base64. However, it does not disclose any side effects like cache regeneration (mentioned only in the schema), nor does it state that validation reports require edit access. It neither contradicts annotations nor adds substantial behavioral richness beyond 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?

The description is three sentences with no fluff. The first sentence states the main purpose and the kind alternative; the second maps formats to kinds; the third notes base64 encoding. Every sentence earns its place, and the key information is efficiently front-loaded.

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

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

Given the tool has an output schema and full schema parameter descriptions, the description covers the critical decision points: which kind to export, which formats are compatible, and how binary artifacts are returned. It does not repeat schema details like the edit-access requirement for validation reports, which is acceptable because the schema already provides it. Overall, an agent can invoke the tool correctly with the combination of description and schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by explicitly mapping allowed formats to each kind (PPTX only for brief, XLSX only for validation report), which is critical for format selection. It also clarifies the output return as base64, adding value for the format parameter and expected result handling.

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

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

The description clearly states the specific verb 'Exports' and the resource: an Audience brief or its validation report. It also distinguishes between the two export kinds and, by naming 'Audience', inherently differentiates from sibling export tools like export_study or export_heatmap. The resource specificity is enough for an agent to select this tool correctly.

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

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

Usage is implied by the resource name: it exports audience-related content. However, the description does not explicitly state when to choose this tool over alternatives (e.g., no mention of 'use export_study for studies') nor does it outline prerequisites such as edit access for validation reports. It is not misleading, but the guidance is implicit 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 provide readOnlyHint=false, destructiveHint=false, but no explicit hints on safety. The description adds that it returns a ZIP archive, and mentions the force parameter regenerates the archive instead of returning cached. However, it doesn't disclose potential side effects like generating a large file or requiring specific permissions. The description adds some context but not extensive.

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 concise, two sentences, front-loaded with the main action and key identifier, then details the contents of the ZIP. No waste.

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

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

Given the tool has an output schema (ZIP contents described), the description doesn't need to explain return values. It does mention the force parameter indirectly by saying 'same ZIP archive as the web app'. The main gap is lack of explicit when-to-use guidance, but overall it's complete 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 covers 100% of parameters with descriptions, so baseline is 3. The description adds no extra meaning beyond the schema, but the schema itself is descriptive (e.g., messageId is 'ID of the completed Study result...'). Thus the description doesn't need to compensate.

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

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

The description clearly states the tool exports a completed website heatmap from a Study result, identified by messageId. It specifies the exact resource (completed heatmap), the action (export), and the key identifier (messageId), which distinguishes it from siblings like export_study or run_study_heatmap.

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

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

The description indicates when to use this tool: when a Study result is completed and reports a message ID. It does not explicitly mention when not to use it or name alternatives, but the context of exporting a heatmap is clear. Since it's the only export-specific heatmap tool among siblings, this is sufficient.

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 false and thus convey no behavioral claims, so the description carries the burden. It discloses meaningful behavioral details: the selection scope (newest 1,000 Minds), the default inline Markdown return, and that PDF/DOCX/PPTX are returned as base64 with a workspace link. It stops short of mentioning side effects, auth, or rate limits, but for an export operation this is reasonably transparent.

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, both information-dense and front-loaded. The first sentence covers purpose and selection; the second covers output formats and delivery. There is no repetition or filler, and the description 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?

Given that a full output schema exists and parameter descriptions cover all four parameters, the description is adequately complete. It explains the core call behavior and selection semantics. It does not cover error conditions or prerequisites, but those are not essential for an export tool with this level of schema support.

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. The description adds value beyond the schema by explaining that fuzzy matching applies to the newest 1,000 Minds and clarifying that Markdown is returned inline by default, which reinforces and slightly extends the format parameter semantics. It does not cover the force parameter, but that parameter's own schema description is sufficient.

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 ('Generates') and resource ('Mind persona profile'), and scopes it to 'one existing Mind' with exact ID or fuzzy name match among the newest 1,000 Minds. This clearly distinguishes it from sibling export tools like export_audience, export_study, and export_heatmap, which target different resource types.

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 provides clear context on when to use the tool (to export a Mind persona profile) and describes the primary selection modes (exact ID vs fuzzy name). However, it does not explicitly exclude alternatives or state when not to use this tool in favor of a sibling, so it misses the highest bar for explicit usage routing.

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

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

It discloses the asynchronous execution model and the job-ID return, which are not visible in the annotations. It does not describe job lifecycle, caching side effects, or permissions, but the schema's force parameter hints at caching; overall this is useful behavioral context beyond the structured hints.

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 async behavior and job ID are front-loaded, and the supported format matrix follows. 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?

Given the fully self-describing schema (100% coverage, enums, nested object, defaults) and the presence of an output schema, the description provides the high-level contract an agent needs: async, job-ID-returning export with a clear format/kind matrix. No critical invocation detail is missing at the description level.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, enums, defaults, and the nested study object. The description mentions the supported formats and report kinds, but that information is already present in the schema and adds no new parameter-level meaning.

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 (starts an asynchronous export), the resource (Study results), and the returned artifact (export job ID). This clearly separates it from sibling export tools that target audiences, heatmaps, or mind maps.

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 makes it clear the tool is for Study-result exports, but it does not explicitly state when to prefer it over export_audience, export_heatmap, or export_mind, nor does it list any exclusions. Usage is implied by the resource name and format list, not 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 readOnly, idempotent, non-destructive and openWorld=false, so the safety profile is covered. The description adds a genuine operational guarantee beyond that — it does not start or retry creation — which matters for an agent deciding whether this call has side effects. No polling/refresh guidance is given, keeping it below 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?

Two short sentences, front-loaded with the read scope and closed with the negative side-effect guarantee. 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-value detail is rightly omitted, and the description covers scope plus the key non-mutation guarantee. It is nearly complete for a single-param read tool, lacking only any hint about progress semantics or whether repeated polling is expected.

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

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

Schema description coverage is 0% for the single required operationId, and the description only implies it identifies 'one Audience creation operation' without naming the parameter or explaining any constraints. The format constraint lives in the schema, so this is a marginal addition — baseline 3 given one undocumented param.

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

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

States a specific verb (Read) and resource (one Audience creation operation plus members' training progress), which is distinguishable from create_audience_from_brief and list_audiences. It does not explicitly name a sibling, so it falls 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?

The clause 'Never starts or retries creation' implicitly routes the agent here for polling rather than for triggering creation, which is useful. However, no alternative tool is named and no explicit when-to-use condition is given, so guidance remains 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 declare readOnlyHint=true and idempotentHint=true, so no side effects are expected. The description adds valuable behavioral context beyond annotations by explaining the distinct meanings of the two mode ceilings, the MODE_CAP refusal behavior, and that the response identifies the account/team which may differ from other connectors. It also clarifies the data scope (per-Audience, not workspace), giving the agent a full picture of the tool's semantics.

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 appropriately detailed without waste. Each sentence serves a distinct purpose: defining outputs, stating relevance, clarifying field semantics, and disambiguating scope. It is well-structured and front-loads the core purpose before diving into nuances. No redundant phrasing 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?

Given the tool's simplicity (one optional parameter) and the presence of an output schema, the description is remarkably complete. It explains the meaning of the returned fields, when to use the tool, and the error condition (MODE_CAP). It covers all aspects an agent needs to call it correctly and interpret results. There are no apparent 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?

The single parameter 'mode' is fully described in the schema (enum with three values, each with a description), giving 100% schema coverage. The description goes further by explaining the practical implications of each mode (e.g., only balanced has an explicitCountCeiling) and the effect of omitting the parameter. This enriches the schema's semantics and helps the agent choose the right value.

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 precisely states the tool returns 'Audience size ceilings' for the authenticated account, listing specific components (per-Audience plan cap, custom-size maximum, per-mode ceilings). It further disambiguates the meaning of the returned fields (automaticSizingCeiling, explicitCountCeiling, memberCap) and clarifies what these are not (workspace capacity, credits, reservation). This is a specific verb+resource action that clearly differentiates from sibling tools like list_audiences or create_audience_from_brief.

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 states when the tool is relevant: 'Relevant whenever a size is named, "as many as possible" is asked for, or a creation mode is chosen.' It also explains the nuanced behavior of mode ceilings and which mode has an explicit cap, warning that exceeding it is refused with MODE_CAP. This provides clear contextual guidance without ambiguity and implicitly tells the agent when to consult this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds credible behavioral context: in-flight questions report zero Minds without indicating a stuck run, locale is only the display locale, and response size grows with questions × Audiences × Minds × answer length. This exceeds what the annotations alone 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?

Four short paragraphs front-load purpose and then add caveats and parameter-selection guidance; almost every sentence contributes behavioral or routing information. The 'Study deletion is not available here' note is somewhat tangential, keeping this from a perfect conciseness score.

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?

Complexities are well handled: async export polling is described, the in-flight zero-edge case is explained, parameter combinations are specified, and return values are covered by an output schema. Given the nested schema and 22 siblings, nothing essential for selecting or invoking this tool 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?

Input schema has 100% description coverage, so the baseline is high; the description adds combination semantics such as passing either questionId or runId and the response-size warning when both are omitted. This goes beyond the per-field schema docs but is not exhaustive for every nested field, hence a 4.

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 and resource ('Returns a Study's current state') and lists substantial return contents including progress, per-Audience results, linked Minds, Study links, and export job status. It is clearly not just a summary, but it never names or contrasts the sibling get_study_summary, so it stops short of explicit 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?

Explicitly describes when to pass questionId vs runId and what happens with neither, which is strong selection guidance within the tool. It does not, however, contrast this read tool with siblings like get_study_summary or route export creation to export_study, so cross-tool usage guidance is 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?

Annotations already indicate readOnlyHint=false, openWorldHint=true, and destructiveHint=false, so the non-read-only nature is covered. The description adds that the summary retains heatmap-compatible block metadata for certain analyses, which is a useful output detail, but it doesn't disclose side effects beyond what 'refreshes' implies. Given the annotations, the description adds modest value without contradicting 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?

The description is a single, efficient sentence that front-loads the core action ('Returns or refreshes') and follows with the output format and a specific metadata detail. Every clause contributes meaning with no waste.

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 presence of an output schema and the annotations, the description covers the main purpose and output format. It doesn't explain the nuances of refresh vs force or study selection, but those are handled by the schema parameter descriptions. For a tool with four optional parameters, this is largely complete, with minor gaps around usage scenarios.

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 75% (three of four parameters have descriptions). The tool description does not elaborate on parameter meanings beyond the schema; it mentions output format but not parameter semantics. The length parameter lacks a description in the schema, and the description doesn't compensate. Since coverage is high, a baseline 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 clearly states the tool's purpose: it returns or refreshes the semantic summary for a Study, and specifies the output as Markdown plus flexible evidence blocks. It also notes a distinguishing detail about heatmap-compatible block metadata for website/image/video analyses, which helps differentiate it from sibling tools like get_study_status or list_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 implies the tool is for retrieving or refreshing summaries, but does not explicitly state when to use it versus alternatives or when to set the refresh or force flags. It doesn't name any sibling tools or give conditions for choosing this tool over others. The usage context is implicit 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 indicate idempotence and non-destructiveness; the description reinforces this with 'Identical file imports are safe to retry' and adds material behavioral caveats: it creates no Audience or Minds, performs no web search, and does not independently verify supplied percentages. It also discloses the return of a normalized snapshot and checksum.

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 no filler; every statement earns its place. Key constraints are front-loaded, such as accepted formats, inline content, retry safety, and the no-verification caveat.

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 3-parameter schema, output schema, and annotations, the description is complete enough for an agent to invoke it correctly. It covers parameter intent, ordering, side-effect boundaries, safety, and even foreshadows the normalized snapshot and checksum return without duplicating the output schema.

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

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

Only 33% of schema properties carry descriptions, but the description compensates well. It explains acceptable file formats and inline content, names and orders the binding of existingFiles followed by files, and frames groundingJson as optional caller-reviewed distribution JSON. This adds real meaning beyond the raw 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 opening sentence names a specific verb ('Imports'), a clear resource ('UTF-8 text, Markdown, CSV and JSON research files'), and the destination ('account-owned storage'). It also distinguishes itself from audience-creation siblings by explicitly stating it 'creates no Audience or Minds.'

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 practical invocation context: callers must supply file contents rather than local paths, may pass optional grounding JSON, and can safely retry identical imports. It does not name sibling alternatives or provide explicit 'use this when' conditions, but the boundaries are clear enough because it states what the operation does not do.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond that: one-page-at-a-time pagination with nextOffset continuation, 'most recently updated first' ordering, searchQuery returning the best fuzzy match 'instead of a page,' and the nuance that workspaceUrl stays valid verbatim while sharedAudienceUrl is the public share link.

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

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

A single dense paragraph with no filler, front-loaded with the core list behavior before parameter and URL details. The heavy parenthetical style makes it slightly harder to parse than a bulleted structure, but every clause earns its place and 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?

With an output schema present and annotations covering the safety profile, the description covers scope, ordering, pagination, returned fields, both optional parameters, and URL semantics. Only edge-case behavior (e.g., empty searchQuery results or no matching names) is left unspecified, which is a minor gap for an otherwise complete read-only 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 input schema already documents all four parameters (100% coverage), so the baseline is 3. The description adds cross-parameter semantics the schema cannot express: searchQuery overrides pagination rather than filtering within it, includeMinds extends each Audience with member Minds, and nextOffset serves as the continuation cursor. This meaningfully exceeds the baseline.

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

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

The description names a specific verb (Lists), resource (the authenticated user's Audiences), and ordering (most recently updated first), which clearly distinguishes it from siblings such as list_studies, export_audience, and ask_audience. Its scope, pagination, and optional-behavior details make the purpose unambiguous even before consulting the schema.

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

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

The description establishes clear context: this is the paginated-listing tool for the user's own Audiences, with searchQuery and includeMinds as behavioral alternatives. However, it never names a sibling explicitly or states a 'when not to use' condition, so exclusion guidance 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?

The annotations already mark this as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds behavioral value beyond annotations by specifying the output's distinguishing dimensions (availability, complexity, executable status, fallback metadata) and the executable vs. experimental/planned distinction.

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

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

Two sentences with no filler: the first identifies the resource and the fields returned, and the second adds the key categorical distinction. The most important scoping information is front-loaded.

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

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

For a read-only list tool with one optional, well-documented parameter and an output schema, the description provides everything an agent needs to invoke it correctly. It communicates the purpose, the returned metadata dimensions, and the dynamic executability distinction 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%, so the includePlanned parameter is fully self-documenting in the schema. The description does not add detail about the parameter, but it is consistent with the schema's mention of planned/non-executable methods, so the baseline 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 verb ('Lists') and a specific resource ('Minds research methods'), and adds the key distinguishing attributes: availability, complexity, executable status, and fallback metadata. It also clarifies that the method distinguishes executable from experimental/planned methods, so an agent can tell it apart from sibling list tools such as list_studies or list_audiences.

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 clearly conveys when to use the tool: when an agent needs to enumerate research methods and understand which are currently runnable. It does not explicitly name alternatives or exclusion conditions, but no sibling tool appears to provide this same resource, so the usage context is clear enough.

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 agent knows this is a safe read operation. The description adds context about what the listing includes (audiences, mind counts, message counts, sharing state, links) and what it does not include (Minds and results, which come from study status). It also notes that deletion is not available. This adds value beyond annotations, but it does not describe the exact return structure or output schema, which is partially covered by 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?

The description is well-structured, with the main functionality in the first sentence and important exclusions and context in the second paragraph. It is not overly verbose, but the second paragraph could be slightly more concise. The key information is front-loaded, making it easy for an agent to quickly understand the tool's purpose.

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

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

Given the tool's moderate complexity, the description covers the essential aspects: what it lists, pagination, search behavior, and what it does not include. The output schema exists, so return values are documented. The description is sufficient for an agent to decide when to use this tool and what parameters to set, though it could be slightly more explicit about when to choose this over other list tools.

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 documentation covers all three parameters with detailed descriptions, including limits, defaults, and how to continue pagination. The description adds context about pagination (nextOffset) and the behavior of searchQuery, but the schema already provides clear semantics. Since schema coverage is 100%, the description's added value is moderate but not critical.

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

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

The description clearly states the verb 'Lists' with the resource 'the authenticated user's Studies' and specifies the ordering (most recently updated first) and pagination. It also distinguishes this tool from siblings by noting that Minds and results come from 'Study status' rather than this listing, and that deletion is not available here.

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 clearly states the context of use: to list the user's studies with pagination, and mentions that searchQuery returns the best fuzzy name match instead of a page. However, it does not explicitly state when to use this tool versus alternatives like 'list_study_drafts' or 'list_study_templates', though the description implies the distinction by mentioning the full Study workspace and the lack of deletion.

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, covering the safety profile. The description adds genuine behavioral context beyond this: the dual-mode behavior (list-all vs single retrieve), the 'durable' qualifier distinguishing drafts from ephemeral states, and the scope of what is returned. This is valuable added context with no contradiction to 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?

Two sentences with no filler; the primary listing purpose is front-loaded, and the second sentence clarifies the dual-mode behavior and scoping. Efficient and well-ordered, though it could be tighter still.

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 tool with one optional parameter at 100% coverage, an output schema present, and annotations covering safety, the description is mostly adequate. The main gap is the lack of explicit routing to sibling tools (e.g., using list_studies for completed studies), which is only implied.

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. The description does add some parameter-linked meaning by explaining the behavioral branch: providing a draftId yields the complete saved planning state, while omitting it lists all drafts. This is modest value beyond the schema, not a full compensation, so 3 is appropriate.

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

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

The description opens with a specific verb+resource ('Lists durable unfinished study drafts') and covers the second mode (returning the complete saved planning state for one exact draft ID). It differentiates drafts from running or completed studies, which conceptually separates it from the sibling list_studies, though it doesn't name the sibling explicitly.

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

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

The clause 'Draft records are distinct from running or completed studies' implies when to use this tool versus alternatives like list_studies or save_study_draft, but the guidance is implied rather than explicit. It does not name any sibling or give a clear when-not-to-use directive.

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 behavior. The description adds valuable context beyond annotations: ordering by most used, the list-vs-single mode, and semantics of configuration.methodId and configuration.questions.

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 focused sentences with the primary action and scope front-loaded. The second sentence is dense with useful domain semantics, though phrases like 'fixed, pre-registered instrument' add jargon without much additional 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?

For a simple read-only tool with one optional parameter and an output schema, this covers the essential behaviors: list vs single retrieval, ordering, and key response fields. Pagination and permissions are not mentioned, but annotations and schema fill most of the remaining 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?

The sole parameter templateId has 100% schema description coverage, so the baseline is 3. The description goes further by clarifying the consequence of providing an ID ('returns one exact template'), which explains the parameter's behavioral effect.

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 ('Lists'), resource ('Study templates'), scope ('your own and team-shared'), and behavior ('most used first'). The dual-mode description ('or returns one exact template') clearly distinguishes this from sibling tools like list_studies 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 clearly implies this is the template-listing/retrieval tool, but it never names alternatives or gives explicit when-to-use/when-not-to-use guidance. Routing away from list_study_drafts or manage_study_template is left to the agent's inference.

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

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

Annotations declare only a mutation-shaped safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds substantial behavioral context beyond that: templates are private by default, owner-only sharing, teammates can read/use but not change a shared template, use never launches research, and save.requestId makes creation retry-safe. This is exactly the extra disclosure annotations cannot carry.

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 and multi-sentence, but it is front-loaded with the action set and follows a logical progression (purpose -> sharing -> contents -> method behavior -> use semantics -> revision/retry safety). Most sentences earn their place given the tool's complexity, though the template-adaptation passage is arguably more than an agent needs to select and invoke the 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 complex, nested, five-parameter mutation tool with an output schema (so return values need not be explained), the description covers the critical behavioral and lifecycle concerns: sharing model, use-vs-research separation, revision requirements and retry safety. The main residual gap is per-field semantics for the configuration payload, which neither schema nor description fully addresses.

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

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

Schema description coverage is 0%, so the description must compensate. It does add meaning for methodId (calculator-backed methods design their own tasks), for save.requestId (retry-safe creation), and for expectedRevision (required for update/use), plus sharing maps to isSharedWithTeam. However, name, goal, studyLocale, question response types, attachments, and templateId receive no semantic explanation, leaving much of a 5-parameter nested schema undocumented in both structured and prose form.

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 states a specific verb set (saves, updates, uses) and a precise resource (Custom research template), and immediately distinguishes itself from the delete sibling: 'Deleting one is a separate operation.' An agent can route correctly between manage_study_template and delete_study_template without opening either schema.

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

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

It enumerates the three actions (save/update/use) and gives conditions for each: updates and use require the current revision, and 'use' creates an independent editable draft that 'never starts research' and is finished in the web app. It also names the excluded operation (deletion) explicitly, so the agent knows what this tool will not do.

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

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

Beyond the annotations (destructiveHint/openWorldHint/idempotentHint), the description discloses non-obvious behavior: saving never starts research, a stale revision is rejected, and re-sending a reworded request creates a SECOND draft rather than revising. These are the exact surprises an agent would otherwise hit, and nothing contradicts 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 purpose and revision rule are front-loaded well, and each paragraph addresses a distinct decision (new vs revise, setup scope, request vs questions, ordering/askIf, attachments). It is dense and somewhat long, but almost every sentence carries actionable information rather than 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?

For a complex, deeply nested 7-parameter tool with an output schema, the description covers the full decision surface: creation vs revision, planner vs fixed instrument, skip logic via askIf, and attachment-to-question mapping. Return values are handled by the output schema, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents the parameters and their mutual exclusions. The description reinforces request-vs-questions and the attachment default rules, but adds little meaning the schema does not already carry, matching the baseline for full coverage.

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

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

The opening sentence gives a precise verb+resource+scope: 'Creates or revises a non-executing draft for a multi-question plan inside an existing Study,' and clarifies it never starts research. It is clearly distinguishable in intent from execution tools like run_study_questions, but it never names a sibling tool to route against, 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 gives strong when-to-use and when-not-to-use guidance: two-or-more known questions go in one draft, a one-question draft only for standalone/follow-up research, and explicit new-vs-revise instructions (draft.id + current revision). It does not explicitly name an alternative sibling (e.g. where to execute the plan), so full routing guidance is absent.

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 behavioral details beyond annotations: starting analysis consumes a response per Mind, requires Premium, and that selecting a different video doesn't alter results. It also explains GET vs start behavior and output keying, giving an agent a realistic expectation of side effects and outcomes.

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 compact yet information-dense. It front-loads the core purpose, then details usage, constraints, and side effects without redundancy. Every sentence contributes new information, making it appropriately concise for the tool's complexity.

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

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

Given the tool's dual actions, parameter nuances, and premium requirement, the description covers the essential calling context. Since an output schema exists, return-value details are not needed. The only notable omission is explicit guidance on where messageId/studyId come from, but that is likely inherited from the study context.

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

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

Schema description coverage is 0%, so the description must compensate. It explains assetKey format (upload path or normalized URL) and the action enum's behavioral meaning. However, it leaves messageId (required), studyId, and studyName unexplained, which is a gap for a 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 clearly states the tool reads or starts a question asset heatmap, with a specific verb and resource. It also mentions behavior parity with Minds UI and distinguishes itself from siblings like run_study_questions or export_heatmap by focusing on the asset heatmap aspect for a question.

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 provides concrete usage context: when to pass assetKey (saved path or URL), the difference between start with assetKey (reuse analysis) and without (rerun), and a prerequisite (Premium). It doesn't explicitly name alternative tools, but the guidance is clear enough for an agent to decide when to invoke 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?

With annotations limited to readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true, the description carries substantial extra behavioral weight: pre-queue revalidation with whole-run refusal before 'any Mind is used or any quota spent,' parallel answering with strict per-Mind answer isolation, askIf conditional asking, order-effect disclosure, and post-run contradiction flagging that is 'never changed.' This is rich, decision-relevant execution semantics far beyond what the annotations convey, and nothing contradicts 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?

The description is front-loaded: the opening sentence states purpose and scope, and each subsequent paragraph earns its place by covering validation gates, execution ordering, askIf behavior, and post-run flagging. For a 7-parameter tool with nested objects and an orchestration engine, the length is proportional; there is no filler or repetition.

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

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

Given the tool's high complexity and the existence of an output schema (so return values need not be explained), the description covers the essential runtime semantics comprehensively: atomicity, validation-before-cost, concurrency, askIf routing, and contradiction handling. The only notable gap is the post-queue lifecycle — the description never says how an agent observes the queued run's progress or outcome, though the sibling get_study_status and the output schema partially cover that.

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 each parameter thoroughly; the baseline of 3 applies. The description adds conceptual glue — tying draft+confirmed into a single all-or-nothing execution and explaining that audienceIds/modelConnection scoping happens within one durable run — but it introduces no new per-parameter syntax or format details beyond what the schema 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 first sentence states a specific verb and resource: 'Executes one stored draft revision inside its Study, after the person has explicitly confirmed that exact revision.' It further scopes itself with 'every named module and every question — as a single durable run; there is no per-question or per-module execution,' which clearly distinguishes it from per-item tools and the sibling run_study_heatmap. An agent can tell exactly what this tool does and what it is not.

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 a hard usage gate ('after the person has explicitly confirmed that exact revision') reinforced by the confirmed parameter, and the schema-level parameter docs add situational guidance ('Select only when the user requests it' for modelConnection; 'Omit entirely to use the active Study'). However, it never explicitly names alternatives or exclusion conditions versus siblings like ask_study or plan_study_questions, so it falls just 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 flag destructiveHint=true, and the description goes well beyond that: it discloses that revisions replace saved planning state, stale writes are rejected via expectedRevision, and retryable creation requires a stable idempotencyKey. This gives the agent the full concurrency and retry model, which is exactly the behavioral nuance needed for safe 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?

Four sentences, each carrying distinct information: purpose, payload summary, revision/concurrency behavior, and retry guidance. The main scope is front-loaded and there is no filler or repetition of schema details.

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 7-parameter tool with nested objects and no required parameters, the description covers why to call it, what it saves, and the concurrency/retry model. The presence of an output schema means return values don't need to be described, so nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable relational semantics not obvious from the schema: it explains how draft.id and expectedRevision work together for optimistic concurrency and how idempotencyKey enables safe retries. It also summarizes the payload contents (objective, context, Audiences, method, questions, sources, planner step), tying the parameter groups to their purpose.

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 and resource: 'Creates or checkpoints an unfinished Quick or Custom Study draft without starting research.' It clearly scopes the tool to draft-saving rather than research execution, distinguishing it from siblings like create_study and list_study_drafts without needing to inspect schemas.

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

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

The phrase 'without starting research' provides clear context on when this tool is appropriate—saving or checkpointing planning state—and implies create_study is the alternative when research should actually start. It does not explicitly name sibling alternatives or give exclusions, but the draft-versus-research framing is enough for an agent to make the right choice.

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