Minds: Synthetic Market Research

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

Adds substantial behavioral context beyond annotations (openWorld, non-idempotent): creates a private Study, starts asynchronous Minds, returns Study identifier/links, may reword, may return planning_required. Annotations already declare the mutation/open-world profile, so this extra detail earns a 4. Doesn't cover polling/latency, so not a 5.

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

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

Front-loads the core capability and scope-out in the first sentences, then the reword/planning contract, then attachment notes. Dense but well-structured; slightly long, with attachment detail partially duplicated in the schema, but every section carries distinct routing 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?

Given a complex 6-param tool with nested objects and an output schema, the description covers scope, async behavior, reword/planning behavior, and attachment routing. Output return shape is delegated to the output schema, which is appropriate. Minor gaps: latency/polling expectations for the async answers aren't stated.

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 material semantic guidance beyond the schema: attachments vs textAttachments vs conversationFiles, that pasted material belongs in textAttachments verbatim (not the question), and that MCP cannot read local paths. This is genuine value over the structured fields.

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

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

States a specific verb ('Asks exactly one standalone question') and resource ('one existing Audience'), and explicitly scopes out multi-question requests: 'Out of scope: a questionnaire, battery, section or any request with two or more known questions.' This clearly distinguishes it from siblings like create_study and ask_study.

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 when/when-not guidance: use this for exactly one standalone question; use planned multi-question blocks for batteries. Notes the planning_required fallback for ambiguous requests and the server's reword behavior. An agent knows precisely which request shape selects this tool.

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

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

Annotations already declare mutation, idempotency and open-world. The description adds real behavioral context beyond those: the question text reaches the Minds and can influence answers, so it must carry only respondent-facing content; pasted stimulus material must go verbatim in evidence.textAttachments instead of the question; question types are auto-classified; the result carries question id, status and workspace links. That is meaningful disclosure. It does not cover cost/latency or failure/abort behavior, so not a 5.

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

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

Front-loads the core action and scope in the first sentence, then the out-of-scope exclusion, then behavioral cautions. Dense but every paragraph earns its place. Slightly long, with the attachment sentence trailing at the end, but no filler.

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

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

Output schema exists, so return values need not be explained, and the annotations carry the safety profile. The description covers the highest-risk pitfall (what must not go in the question text) and the attachment routing. It is complete enough to call correctly. Minor gap: no mention of study resolution fallback or error/retry behavior, though the schema covers study selection.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters thoroughly. The description reinforces the critical constraint on the question field and the textAttachments routing, but adds no syntax or format detail 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?

States a specific verb (submits) and resource (exactly one standalone question or adaptive follow-up in an existing Study), and explicitly carves out the out-of-scope case (questionnaires/batteries/multi-question blocks) which is what distinguishes it from a planned block flow and from 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?

Explicit when-to-use (one question, or an adaptive follow-up whose wording depends on earlier results) and when-not-to-use (two or more known questions belong in a planned confirmed multi-question block, submitted once). It names the alternative path rather than leaving the routing to inference.

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

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

Goes well beyond the annotations: it discloses the additive-only semantics, that retries are safe (corroborating idempotentHint), that access and plan eligibility are validated first, and a genuine side effect — with link sharing on, the Audiences and their Minds become publicly readable. That privacy consequence is not derivable from destructiveHint=false or openWorldHint=true.

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

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

Three tightly packed sentences with the core action front-loaded, followed by return values, retry safety, side effect, and preconditions — no filler or redundancy despite the density.

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-shape explanation is not required, and the description still names the attached/alreadyAttached result fields. Combined with annotations and 100% schema coverage, it supplies everything needed to invoke the tool correctly, including the public-visibility caveat.

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 both parameters are documented in detail (uuid patterns, 1–50 item bound, study id/name precedence, active-Study fallback). The description only restates the 'existing, accessible' qualifier for audienceIds, 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?

Specific verb+resource ('Adds existing accessible Audiences' to a Study) with an explicit scope qualifier — it does not remove others, plan, or start research — which separates it from delete/update/start_study_run siblings. An agent can identify the operation without opening the schema.

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

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

'Adds existing accessible Audiences' plus 'Access and plan eligibility are validated first' constrains when the call applies and implies the audiences must already exist (routing away from create_audience_from_brief / import_audience_sources). No sibling is named explicitly as the alternative, so it stops short of a full when/when-not statement.

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 (which already declare non-read-only, open-world, idempotent, non-destructive), the description discloses that creation is asynchronous and returns an operation ID, that confirmation requires the user-accepted draft/snapshot plus its checksum, and that Audiences are private unless link sharing is enabled. These are material behavioral facts an agent needs before calling.

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

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

Five sentences, front-loaded with purpose and scope, and each sentence carries distinct information (workflow, isolation rule, recalibration rule, dataset support, async, privacy). Sentences are long and dense but not redundant.

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

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

For a 9-parameter nested-object tool with an output schema present, the description supplies the essential mental model (research → draft → review → confirm → async Audience), so return-value detail is correctly left to the output schema. It omits mention of some options (conversationFiles, memberCount tuning), but those are thoroughly documented in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds workflow-level meaning the schema does not: the draft-then-confirm sequence, the fact that confirmation needs the accepted draft/snapshot and checksum, and that rework revises rather than recreates. This clarifies how the parameters interact rather than merely restating them.

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

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

States a specific verb + resource ('Researches a free-text population brief and builds a new Audience of Minds') and frames the scope crisply. It distinguishes itself from the recalibration path by asserting that an existing Audience is changed in place by id and 'never rebuilt from a new brief', so the agent can tell this apart from recalibrate_audience without opening schemas.

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

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

Gives clear context for the new-brief workflow, the draft/rework/review sequence, and an explicit when-not (existing Audience → recalibrate by id). It stops short of naming sibling tools like recalibrate_audience or import_audience_sources for text resources, leaving some routing to inference.

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

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

Annotations cover only the basic safety profile; the description adds substantive behavior beyond them: name-collision no-op semantics, that Studies are permanent and cannot be deleted, that creation is atomic with rollback of partial Audience failures, and that isLinkSharingEnabled publishes every attached Audience and Mind at world-readable URLs, including pre-existing ones. These are exactly the side effects an agent must know before calling.

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

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

Purpose is front-loaded and the ordering (what it does, duplicate handling, multi-question guidance, atomicity, privacy) is logical. It is long for a create tool, and the closing sentence about not publishing/replacing an existing Study is compressed to the point of being ambiguous ('that sharing changes only in the workspace').

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

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

For a 6-parameter mutation tool with an output schema, everything an agent needs is present: collision handling, non-deletability, atomic rollback, and the public-sharing side effect on nested Audiences and Minds. Return values are correctly left to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning to parameters: it frames the duplicate-name case that allowDuplicateName governs and ties isLinkSharingEnabled to publishing attached Audiences and Minds. It stops short of new syntax or edge-case detail for conversationFiles beyond what the schema already documents.

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?

First sentence states a specific verb and resource (creates a Study workspace) and its two input modes (existing Audiences or inline configs), then immediately scopes it against neighbors: 'It does not ask questions or run research.' An agent can distinguish this from ask_study, plan_study_questions, and duplicate_study without opening a schema.

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

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

Explicit when/when-not routing: follow-up research in an existing Study needs no new Study; a same-named Study means 'work in that Study instead' unless allowDuplicateName is true; two-or-more known questions belong in one planned multi-question block rather than separate direct questions. It also names the alternative path (audienceIds vs audienceConfigs) and points to list_audiences.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and non-idempotency, so the safety profile is covered. The description adds value beyond them by clarifying the operation is non-executing, that 'saving bounded history may prune older revisions,' and that the returned draft revision requires review and later explicit confirmation. No return format or pagination detail, but the confirmation/pruning notes are genuine additions.

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 in the first sentence and the remaining sentences are dense but largely earn their place, each carrying a distinct constraint (module grouping, request vs questions, askIf routing, attachment mapping, pruning, confirmation). It reads as a packed block rather than flowing prose, but there is little filler.

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

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

For a 7-parameter tool with nested objects and a high-stakes mutation workflow, the description covers the main invocation paths, the request/questions fork, the confirmation flow, and side effects. An output schema exists, so return-value explanation is not needed. It is complete enough to call correctly, with only minor gaps around multi-call sequencing with revise_study_plan.

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 still adds meaning by stating the mutually exclusive selection heuristic ('request designs questions; questions preserves a fixed instrument verbatim') and clarifying that stimulus.questionAttachments assigns each question with [] meaning none, which helps an agent choose between the two paths rather than just reading field docs.

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 and resource: 'Creates a non-executing draft in an existing Study with its Audiences already attached.' The 'non-executing' scope distinguishes it from start_study_run and the draft/revision framing separates it from create_study, though no sibling tool is named explicitly.

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

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

Gives a clear when-to-use rule ('two or more known questions: every question known now belongs in this one draft') and a when-not ('A one-question draft is only for genuinely standalone research or an adaptive follow-up'). It also routes between the request and questions parameters, but does not name sibling tools like revise_study_plan or save_study_draft as 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 destructiveHint=true and idempotentHint=false, yet the description still adds substantial context: deletion is permanent, ownership is required, and Studies/drafts created from the template are unaffected. The downstream-impact disclosure is exactly the kind of behavior annotations cannot 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 sentences, front-loaded with the scoping constraint before the mechanics. Slight redundancy in stating the ownership restriction twice (once tied to the authenticated user, once tied to shared-access teammates), but every sentence still carries usable information.

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

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

An output schema exists, so return-value explanation is not needed. For a destructive single-param tool, the description covers permanence, ownership/authorization, and side-effect scope on derived Studies and drafts — nothing an agent needs to call it safely 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% and the single param already carries 'Template to delete permanently. Owner only.', so the baseline is 3. The description adds meaning beyond the schema by tying the ownership constraint to the authenticated user and to the teammate-sharing case, which clarifies the authorization model rather than just restating the 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 and resource ('Permanently deletes one template') and immediately scopes it with 'Only for saved Study templates', explicitly excluding Studies, Audiences, Minds and answers. An agent can distinguish this from manage_study_template and list_study_templates without opening any schema.

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

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

Gives clear exclusions ('it cannot delete Studies, Audiences, Minds or answers') and a prerequisite ('owned by the authenticated user', teammates with shared access cannot delete). It does not name a sibling alternative for template modification, but the when/when-not boundary is otherwise 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 declare this as a non-read-only, non-destructive write. The description adds context beyond that: the copy is a deep, independent replica of the Minds rather than a link, so the source is unaffected. It does not mention the copy being private, counting against the Mind allowance, or retraining of copied members, all of which live only in the schema.

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

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

A single tight sentence with the core operation front-loaded and no filler. It is efficient, though arguably under-specified rather than optimally balanced for a mutation tool with this many siblings.

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

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

An output schema exists, so return values need not be explained, and the schema is fully self-documented. What is missing is purely descriptive routing and precondition context for a write operation that sits among many similar-sounding siblings.

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

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

Schema description coverage is 100%, so all three parameters (name, audienceId, idempotencyKey) are already documented with substantial detail in the schema. The description adds no parameter-level information, which is the expected baseline when structured fields do the work.

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

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

States a specific verb and resource (copy an Audience) and immediately scopes what is copied (independent copies of its Minds and all they know), which cleanly separates it from the sibling duplicate_study. An agent can identify the operation without opening the schema.

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

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

The description gives no when-to-use, when-not-to-use, or alternative routing, which matters in a fleet of ~35 siblings that include create_audience_from_brief and duplicate_study. Any preconditions (edit rights, Mind allowance) appear only in the schema, not the description.

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 non-read-only, non-destructive, non-idempotent, so the safety profile is partly covered. The description adds that questions and results are carried over, but omits the paused schedule, the audience-sharing behavior, the live-run refusal, and the retry semantics that the schema documents.

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 twelve-word sentence with the verb front-loaded and zero filler. It is efficient, though arguably too terse to carry any usage or behavioral context.

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

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

An output schema exists, so return values need not be explained, and the annotations carry the safety profile. However, for a mutation tool that can be refused (live run) and whose audience/idempotency behavior matters, the description leaves everything but the bare copy action to the schema.

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

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

Schema description coverage is 100%, so all three parameters (name, studyId, idempotencyKey) are already documented in the schema. The description adds no parameter-level detail beyond what is structured, so the baseline 3 applies.

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

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

States a specific verb (copy) and resource (Study) with scope ('all its questions and results over the same Audiences'). It does not name a sibling to differentiate from, though the 'same Audiences' phrasing implicitly separates it from duplicate_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?

Implies the use case is reproducing an existing study rather than creating one from scratch, but gives no explicit when/when-not guidance or prerequisites. The routing to duplicate_audience and the live-run refusal exist only in the schema, not the description.

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

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

Annotations declare readOnlyHint=false and idempotentHint=false, so the agent knows this produces a non-cached artifact without destroying data. The description adds genuinely useful context beyond that: caching behavior implied by force/regeneration, the base64 encoding of binary artifacts, and the edit-access requirement for validation reports.

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 core action and the kind branch before the format lists. The parenthetical enumeration of report contents is dense but earns its place by clarifying the second mode; there is minimal 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?

With an output schema present, the description needn't explain return values, and it still notes base64 encoding for binary output. Combined with annotations covering safety and the schema covering parameters, the definition leaves nothing an agent needs to call it correctly unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including enums and the audience object. The description largely restates the kind/format matrix (Markdown/PDF/DOCX/PPTX vs Markdown/PDF/DOCX/XLSX) that the schema already covers, adding little new parameter meaning beyond the base64 return note.

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

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

Specific verb (Exports) plus resource (Audience brief) with two clearly enumerated modes (brief vs validation_report), each detailing what is included. This distinguishes it from the sibling export_heatmap/export_mind/export_study tools, which export different artifacts.

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 branches clearly by kind and states format constraints per kind (PPTX brief-only, XLSX report-only), and the schema notes that a validation report needs edit access and a scored validation. However it never states an explicit when-not or names an alternative tool, so the routing guidance is implicit rather than 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 already declare the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description goes beyond them by specifying the return artifact in detail: a unified-renderer PDF report plus Markdown, images, and metadata, matching the web app's ZIP. It does not restate the caching/regeneration behavior covered by the force parameter.

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 zero filler; the action and identifier requirement come first, followed by the return contents. Nothing is redundant.

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

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

With an output schema present, return explanation is optional, yet the description nonetheless characterizes the archive contents. Preconditions and identification are covered; only explicit routing among sibling export tools 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 messageId, study, and force. The description only reinforces that messageId comes from the completed result, adding minimal meaning 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?

States a specific verb (Exports) and resource (website heatmap from a Study result), and the required identifier (messageId). An agent can distinguish it from export_study, export_mind, and export_audience, which target different artifacts.

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

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

It implies the correct precondition (a completed Study result carrying a heatmap, whose message ID is reported on completion), which routes the agent after run_study_heatmap finishes. However, it gives no explicit when-not guidance or named alternatives for overlapping export 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?

Annotations declare readOnlyHint=false with destructiveHint=false, consistent with generating artifacts. The description adds real behavioral context beyond that: markdown is returned inline by default, while PDF/DOCX/PPTX come back base64 with a workspace link, and fuzzy name resolution can select a different Mind than intended. It stops short of describing caching semantics or side effects of artifact generation.

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

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

Two dense sentences, front-loaded with what the tool produces and the identification mode, then the output-format contract. Every clause carries information; nothing is padding.

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

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

An output schema exists, so return values need not be explained, and the description still supplies the key output-format contract (inline markdown vs. base64 artifacts). With zero required parameters and full schema coverage, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so baseline is 3, and the schema already documents format, force, mindId, and mindName. However, the description adds meaning beyond the schema by clarifying that partial names and typos resolve to the closest match, which sharpens the fuzzy-matching semantics the schema only labels tersely.

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 (branded profile for one Mind), and clearly separates this tool from siblings like export_audience, export_study, and export_heatmap by naming the Mind object as the target. It also specifies the identification method, so an agent can distinguish it without opening the schema.

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

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

The description implies usage by explaining identifier handling and default vs. non-default formats, but never states when to choose export_mind over the sibling exports or when not to use it. Standard for a tool with 100% schema coverage, but no explicit routing guidance is given.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is partly covered; the description adds the genuinely new fact that execution is asynchronous and returns a job ID rather than the artifact itself. It still omits how to retrieve or poll the resulting export and whether artifacts expire, but the async disclosure is material context beyond the structured fields.

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

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

Two sentences, front-loaded with the async behavior and job-ID return, then the supported output combinations. It is tight overall, though the format enumeration partially duplicates the schema enum and consumes half 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?

An output schema exists, so return-value structure need not be explained, and the 100%-covered input schema handles the parameters. The description supplies the essential async/job-ID framing; the remaining gap is the lifecycle around the job ID (polling, expiry), which an agent will likely need but may find in the output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the format set (PDF, DOCX, PPTX, Markdown, CSV, XLS, SAV) and the report kinds already enumerated in the schema, and adds no new meaning for force, length, scheduledRunId, or the nested study selector.

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 ('Starts an asynchronous export of Study results') plus the observable result ('returns an export job ID'), which is enough to distinguish it from sibling exports like export_audience, export_heatmap, and export_mind. It does not, however, explicitly differentiate itself from render_study_results, which an agent must also weigh when choosing a results-output path.

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 when-to-use guidance, no prerequisites, and no alternatives. It never tells the agent when to prefer this async export over render_study_results, nor when to choose raw_data versus full_report. Usage must be inferred entirely from the schema enums.

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. The description adds real value on top: it enumerates what each mode surfaces (members' training, background research, retained result or terminal error) and the readiness condition for validation and final scores. It stops short of describing polling cadence or whether progress is eventually consistent.

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

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

Front-loaded with the scoping statement ('reads progress and never starts or retries anything'), then the three lookup modes, then the readiness rule. Dense but every clause carries information; the mid-sentence list structure is slightly harder to parse than 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?

Covers all three identifier modes, the readiness requirements, and what each path returns; an output schema exists so return format need not be restated. Missing only secondary operational details such as whether repeated polling is expected or how stale results may be.

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 relational semantics the schema does not: recalibrationId only makes sense 'with audienceId', and it is the operation id returned by recalibrate_audience. That pairing constraint is genuinely useful invocation guidance.

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

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

States a specific verb (reads progress) and resource (Audience creation / member training / recalibration), and immediately clarifies it 'never starts or retries anything', distinguishing it from start_study_run, resume_study_run, and recalibrate_audience. An agent can tell what it returns without opening the schema.

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

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

Explicitly routes by identifier: operationId for an in-flight creation, audienceId for an existing Audience, audienceId+recalibrationId for one recalibration's status. States the negative case (it never starts or retries) and gives an operational readiness rule ('Validation needs 10 ready members; for a final score wait until all are trained and research is done').

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower, yet the description adds real semantic context: it explains what automaticSizingCeiling vs explicitCountCeiling bound, notes that only 'balanced' carries an explicit ceiling, and states that in deeper modes a stated size is bounded by memberCap alone. It does not address auth requirements, so 4 rather than 5.

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

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

The purpose is front-loaded in sentence one, and the exclusionary sentences ('These are per-Audience sizes, not workspace capacity...') earn their place by preventing a real misreading. Some sentences are dense and the last two overlap conceptually, so it is efficient but not maximally tight.

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

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

With an output schema present the return values needn't be explained, yet the description supplies the boundary conditions an agent needs to interpret them correctly and explicitly rules out what the numbers are not (workspace capacity, credits, reservation, remaining balance). For a one-optional-parameter read-only tool, nothing needed 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% and the single enum parameter is already documented ('Report only this creation mode. Omit to see every mode.'). The description elaborates mode-related behavior indirectly (which ceiling applies per mode), which adds marginal value, but the parameter contract itself is fully carried by the schema — 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 first sentence names a specific verb and resource — it returns the audience size ceilings for the authenticated account before an Audience is created — and enumerates the concrete ceilings (plan cap, custom-size maximum, per-mode ceilings). This clearly distinguishes it from creation siblings like create_audience_from_brief and recalibrate_audience, so an agent can route to it without opening the schema.

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

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

It gives explicit triggering conditions: 'whenever a size is named, "as many as possible" is asked for, or a creation mode is chosen.' That is clear when-to-use context, but no when-not conditions and no named alternative sibling for comparison, so it stops short of the top band.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior. The description adds no behavioral context beyond annotations, such as auth requirements, exclusion rules, or return behavior.

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

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

The description is a single, front-loaded sentence with no wasted words. It is appropriately concise, though its brevity borders on under-specification for a tool definition.

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

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

The output schema exists, so return values need not be explained in the description. Annotations cover safety and idempotency, and the input schema fully documents the sole parameter. The description states the core operation, making the overall definition complete enough for a simple read tool.

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

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

Schema description coverage is 100% for the single required parameter. The schema fully documents that shareId is a UUID from /minds/shared/{shareId}, must be public or link-enabled, and excludes certain data. The description adds no parameter meaning, so baseline 3 applies.

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

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

States a specific verb ('Read') and resource ('shared Mind sources and assessments'). The purpose is clear but does not explicitly differentiate this tool from any sibling, though no sibling appears directly comparable.

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 no guidance on when to use this tool, prerequisites, or alternatives. It simply states the operation, leaving the agent to infer usage from the name and schema.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value on top: it signals no cost is incurred ('spending responses'), no external fetching occurs ('visiting websites' — consistent with openWorldHint=false), and only already-saved data is returned.

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

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

Three tight sentences with purpose front-loaded and zero filler. The final clause is dense ('spending responses' is slightly cryptic) but every sentence carries information, so it is appropriately sized.

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 shape need not be described, and annotations cover the safety profile. However, the required messageId and the studyId/studyName parameters are unexplained, leaving the agent without enough to know how to key the call correctly.

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

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

Schema description coverage is 0% for all four parameters, so the description carries the full burden, and it only explains one: assetKey ('selects its saved upload path or normalized URL'). The required messageId, plus studyId and studyName, are left completely undocumented in both schema and description, which is a significant gap for the sole required parameter.

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

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

States a specific verb and resource ('Reads saved heatmaps of an assigned question asset'), which is a distinct action from the sibling start_study_heatmap. The phrase 'without starting analysis' effectively separates it from that sibling, though it never names the alternative explicitly, which keeps it just short of a 5.

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

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

The clause 'without starting analysis, spending responses or visiting websites' tells the agent when this tool is the right choice versus triggering a fresh analysis (start_study_heatmap). There is no explicit when-not statement or named alternative, so it stops at clear-context guidance rather than full routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the description's no-write/no-research claim largely restates structured data. It does add one non-redundant detail, that the read targets the *latest saved* revision, but says nothing about permissions, freshness, or what happens when no revision exists.

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

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

Two short sentences, zero filler, with what it returns and what it does not do both front-loaded. Every clause earns its place.

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

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

With an output schema present and full schema coverage, the description need not explain return values, and it already hints at them (latest revision plus full review). Nested-object targeting and study-resolution behavior are covered by the schema, so only the lack of any alternative-routing leaves a small 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% and the nested study object includes precedence rules (id over name, omit for active Study) plus the required draftPlanId. The description adds no parameter meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb ("Reads") and resource ("one draft" plan), and specifies scope: the latest saved revision plus the full review. It does not name the sibling it is distinct from (render_study_plan, revise_study_plan, list_study_drafts), so differentiation is left to inference.

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

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

The negative constraints ("Creates or changes nothing and starts no research") imply this is the read-only counterpart to revise_study_plan/start_study_run, but no alternative is named and no condition for choosing it is given. Usage is implied rather than stated.

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

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

Annotations only cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely non-obvious behavior: in-flight questions report zero Minds answered until completion, partial per-Mind progress is not persisted, and the locale resolution order (confirmed plan language, else stored Study locale, else English). These directly shape how an agent interprets the returned values.

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 what is returned, then behavioral caveats, then parameter selection, then locale. Four sentences with little waste; the locale sentence is dense but precise and earns its place. No filler or repetition of the name.

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

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

An output schema exists, so return values need no explanation, and annotations cover the safety profile. For a zero-required-parameter status tool with nested objects, the description supplies the missing pieces an agent needs: scope selection, in-flight caveats, and locale resolution.

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 interaction semantics the schema does not state on its own: questionId narrows to one question, runId returns the confirmed run with question-level counters, and supplying neither yields the whole-Study view. It also reinforces the locale behavior of returned labels.

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 and enumerates exactly what is returned (progress, per-Audience results, original Mind responses, links, export status), which is more than a restatement of the name. It never names a sibling (get_study_plan, read_study_summary, export_study) to draw the boundary explicitly, so sibling differentiation is implied rather than stated.

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

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

Gives clear context for how to select scope: 'questionId selects one question; runId selects a confirmed run... Without either, results cover the entire Study.' It also notes questionId 'keeps the response small.' It stops short of naming alternatives (e.g., read_study_summary or get_study_plan) or when not to use this tool, so it is clear context without 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 establish the safety profile (readOnly=false, idempotent=true, destructive=false), so the bar is lower. The description still adds real value beyond them: retry safety, the no-Audience/no-Minds side-effect boundary, and the absence of independent verification of supplied percentages. Auth requirements and limits are not mentioned, keeping it from a 5.

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

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

Four sentences, each carrying distinct information, with the core action and input constraint front-loaded. The middle sentences about grounding JSON and source ordering are dense but earn their place; slightly tighter phrasing could improve scanability.

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-style ingestion tool with an output schema, the definition covers inputs, ordering semantics, idempotency, and non-effects well. Remaining gaps are operational details (permissions, size/item limits) that an agent might want before calling.

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

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

Schema coverage is only 50%, so the description must compensate, and it does for the critical parts: file-contents-not-paths for 'files', and the source binding order of existingFiles, then files, then conversationFiles in sourceIdx order. It does not clarify maxItems/count limits or the 5MB content cap, so it is not fully compensating.

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 ('Imports ... research files into account-owned storage') plus accepted formats and the key constraint that it takes file contents rather than paths. An agent can immediately separate this ingestion tool from siblings like create_audience_from_brief or plan_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 clear context for when the tool applies (supplying file contents, optional grounding JSON for preview/creation) and explicitly scopes it out of audience/mind creation and web search. It never names a sibling alternative for the excluded cases, so it falls just short of an explicit when/when-not routing statement.

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, yet the description adds substantial behavioral context beyond them: page-at-a-time iteration via limit/offset/nextOffset, most-recently-updated ordering, name-filter matching rules, and the meaning of output fields like workspaceUrl (valid verbatim), sharedAudienceUrl, and addOnRequired.

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 that is front-loaded with the core purpose and iteration model before drilling into filter and field semantics. Every sentence carries information, though it is tightly packed for one block of prose.

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?

Even though an output schema exists and return values needn't be explained, the description goes further by clarifying ambiguous output fields (workspaceUrl vs sharedAudienceUrl, addOnRequired) and the pagination contract. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including defaults, ranges, and nextOffset continuation. The description largely restates these (limit default 20, offset/nextOffset, includeMinds adds member Minds), adding little syntax or meaning the schema does not already carry.

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

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

States a specific verb and resource with scope: 'Lists the authenticated user's Audiences', and adds ordering and pagination semantics up front. It is immediately distinguishable from siblings like list_studies or list_study_drafts, which operate on different resources.

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 some operational guidance ('Omit to browse' for searchQuery, default includeMinds=false) and a directive about addOnRequired ('prefer the user's own Audiences, and only use it after the user subscribes'). However, this is guidance about interpreting results rather than explicit when-to-use/when-not and no alternative sibling is named.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine context beyond them: the catalog is fixed, includePlanned has no side effects beyond filtering, and mutation is impossible through this tool. It stops short of describing result ordering or size, hence not a 5.

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

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

Two tight sentences, front-loaded with what the tool returns followed by the boundary conditions. Every clause earns its place; nothing is repeated from the schema or annotations.

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

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

An output schema exists, so return-value detail is not required here, and annotations cover the safety profile. For a zero-required-parameter read tool, the description supplies everything an agent needs: scope, what it returns, and what it cannot do.

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

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

Schema description coverage is 100% and the single parameter is already well documented in the schema, including the executable:true caveat. The description's "includePlanned only filters the returned catalog" adds only a mild reinforcement of that parameter's semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ("Reads the fixed Minds research-method catalog") and enumerates the returned fields (availability, complexity, fallback method). No sibling tool covers a method catalog, and the description explicitly rules out the confusable write operations (create/configure/execute), so an agent can place it instantly.

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

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

Clearly frames the tool as a read-only catalog lookup and states what it does NOT do ("does not create, configure or execute a method, and the catalog cannot be edited through this tool"). It gives exclusions but no named alternative for related tasks, which is acceptable since no sibling overlaps.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond them: page-at-a-time iteration with nextOffset, default page size, newest-first ordering, and the notable edge case that searchQuery returns the closest name when nothing matches.

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 and front-loaded with the resource and ordering first, then pagination, then filtering. The middle sentences are slightly run-on and interleave return-shape detail with parameter behavior, but nearly every clause carries information.

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

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

An output schema exists, so return values need not be fully described, yet the description still summarizes row contents (Audiences, Mind counts, message count, sharing state) and the pagination continuation. Combined with full annotation coverage, an agent has essentially everything needed; only the absence of any routing to sibling list tools leaves a small 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 the schema already documents limit (default 20, max 100), offset (continue via nextOffset), and searchQuery semantics. The description restates these rather than adding format or syntax detail, so the baseline 3 applies.

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

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

States a specific verb and resource (Lists the authenticated user's Studies) plus scope, ordering (most recently updated first), and pagination model. An agent can distinguish it from list_audiences, list_study_drafts, and list_study_templates without opening any schema.

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

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

Gives clear context: use searchQuery to filter by name, 'Omit to browse', and explicitly routes detail needs elsewhere ('Minds and per-question results come from the Study status'). It never states exclusions or when a different list tool is preferable (e.g. list_audiences vs this), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds the newest-first ordering and the draft-vs-study distinction, which is genuine value, but says nothing about pagination behavior or cursor semantics beyond what the schema states.

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

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

Two sentences, zero waste, and the dual behavior is front-loaded so an agent immediately knows both modes. 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?

With an output schema present and rich annotations, the description needn't explain return values, and it correctly focuses on the two modes plus the draft/study distinction. It is essentially complete, missing only explicit routing to sibling 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?

Schema description coverage is 100%, so the schema fully documents limit, offset, draftId, and searchQuery. The description reinforces draftId's role ('complete saved planning state') and ordering, but adds little meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Lists a page of unfinished Study draft summaries' / 'returns the complete saved planning state for one exact draft ID') and covers both operating modes. It distinguishes drafts from running/completed studies, which separates it conceptually from list_studies, but never names sibling tools 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 two modes are implied (paginated list vs. single-draft retrieval) and the distinction from running/completed studies gives some selection context. However it never names alternatives like list_studies or save_study_draft, and gives no explicit when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real context beyond that: ordering ('most used first'), paged summaries, and the note that configuration.questions is a pre-registered instrument with configuration.methodId as its method.

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?

Reasonably front-loaded with the core listing behavior, but the second sentence about configuration.questions and configuration.methodId is dense and jargon-heavy, diluting an otherwise tight definition.

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

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

An output schema exists, so return-value detail isn't required from the description. Combined with annotations covering the safety profile and a 100%-covered input schema, the description covers listing, filtering, paging, and single-record retrieval adequately.

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 reinforces templateId's dual role and mentions paging/search context, but adds little syntax or meaning beyond what limit, offset, templateId, and searchQuery already document.

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) and resource (Study templates), and clearly covers both modes: a page of summaries or one exact template by templateId. The scope 'your own and team-shared' is useful. It does not explicitly differentiate itself from siblings like list_studies or list_study_drafts, leaving that distinction to the reader.

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 describes the two behaviors (list summaries vs. fetch one by templateId) so the choice between modes is implied by whether templateId is given. However, there is no explicit when-to-use guidance relative to list_studies, list_study_drafts, or manage_study_template.

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

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

Goes well beyond the annotations: annotations only flag destructiveHint=true, but the description explains what destruction means ('Revocation stops new work at checkpoints; completed changes remain') and who may act ('Staff cannot self-grant'). It does not restate the idempotency hint, which the schema's requestKey covers. No contradiction with the declared 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?

Three tight sentences, purpose front-loaded, followed by the authorization rule, the revocation semantics, and the scope boundary. Every clause earns its place with no padding 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?

For a five-action mutation tool with a full output schema and complete parameter coverage, the description supplies the behavioral essentials (authorization, revocation semantics, exclusions). The one gap is that the action set and the per-action permission rules live entirely in the schema enum description rather than being summarized.

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 every action-specific parameter is documented in the schema (reason, grantId, expiresAt, requestKey, cursor, audienceId). The description's only related signal is 'expiring', which adds nothing to the schema's 'expiry within 30 days'. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource: managing owner-issued, expiring staff access to one Audience's composition and receipts. It also carves out scope ('No membership, growth, deletion or billing changes'), which separates it from the other audience/study siblings. It stops short of naming a sibling or mentioning that this is a five-action tool (list/grant/revoke/activity), which the schema carries instead.

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?

'Staff cannot self-grant' plus 'owner-issued' imply the authorization context for when grant/revoke is appropriate, but there is no explicit when-to-use-this vs. an alternative tool or action. The action enum descriptions carry the operation-selection guidance, so usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description's 'does not regenerate or replace' is largely a restatement of read-only behavior, adding only the mild signal that no regeneration compute/side effect is triggered; nothing about auth, limits, or output shape is added.

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

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

Two short sentences with zero waste; the positive statement of what is read comes first and the negative constraint second. Every clause earns its place.

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

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

An output schema exists, so return values need not be described, and the schema fully documents the single nested study parameter. The only meaningful gap is not explicitly routing the agent to refresh_study_summary for regeneration.

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 itself documents the id-over-name precedence and the omit-both-to-use-active-Study fallback. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb (reads) and resource (saved whole-Study summary), and enumerates the content returned: Markdown, evidence blocks, metadata. The negative clause 'does not regenerate or replace' implicitly separates it from the refresh_study_summary sibling, though that sibling is not named.

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

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

The tool is only implicitly positioned: 'does not regenerate or replace' hints that regeneration is a different tool's job, but no condition, prerequisite, or alternative is stated explicitly. An agent must infer that refresh_study_summary is the counterpart.

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

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

Adds substantial context beyond the annotations: asynchronous accepted-operation semantics with an operation id, queuing behind another edit and waiting for a Study run, the permission model (owner vs. verified staff with collaboration or support grant), shared members being replaced by copies with new ids, and safe retry via requestKey. The retry-key wording is consistent with idempotentHint=false rather than contradicting it, and it explains what is and is not destroyed (no Mind deleted, ids preserved).

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

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

Core purpose is front-loaded and every sentence carries operational weight (permissions, async behavior, shared-Mind copying, retry safety). It is, however, extremely dense and contains material that overlaps with the already-verbose schema descriptions, and the opening parenthetical "(except copies below)" is noise that points at content far downstream.

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

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

For a destructive, open-world, non-idempotent mutation tool this is comprehensive: it covers permission prerequisites, sequencing/queueing, the accepted-operation return shape, shared member copying, and idempotency recovery. With an output schema present, it correctly does not waste space explaining return payload fields.

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

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

Schema description coverage is 100% and the nested schema descriptions are themselves highly detailed (deepen, distributions, research, allowSharedMinds, conversationFiles all carry their own semantics), so the schema already does the heavy lifting. The description adds little parameter-level meaning beyond the schema, other than restating which fields make up the edge set; a baseline 3 is appropriate.

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

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

States a specific verb+resource ("Changes an existing Audience in place") and then enumerates the concrete change modes it covers: composition and trait edits, population pivot, adding members, exact chart selection, deepen, and research re-grounding. An agent can distinguish this from create_audience_from_brief or duplicate_audience without opening any schema, and it even clarifies that asking for a "version" here leaves this Audience untouched.

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

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

Gives an explicit routing rule ("Use this, not query, to adjust the Audience") plus a when-not in the permission clause (staff support is limited to composition amendments: no growth, new sources, Go deeper or shared-Mind waiver). The alternative it names, "query", is not an actual sibling tool name, which slightly weakens the routing compared with naming ask_audience or duplicate_audience directly.

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

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

Beyond annotations that already flag destructive=true and idempotent=false, the description discloses the exact destruction scope ('replaces the prior summary without restore history') and what survives ('answers and questions are preserved'), plus the return format. This is precisely the added context annotations cannot 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 dense sentences with the mutation and its approval precondition front-loaded; the destruction/reversibility caveat follows immediately. Minor terseness ('force regenerates unchanged coverage') leans on the schema, but nothing is wasted.

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

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

For a destructive mutation, the description covers the prerequisite, the irreversibility, the preserved data, and the return shape; with an output schema present, return values need no more detail. Only the missing pointer to the read-side sibling keeps it from being fully complete.

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

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

Schema coverage is 75%, and the schema already documents force, study, and confirmed in detail. The description restates force's effect ('regenerates unchanged coverage') but adds nothing for study, length, or confirmed, so it neither undercuts nor meaningfully extends the schema.

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

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

States a specific verb pair and resource: 'Generates and saves a whole-Study summary'. The refresh/replace framing implicitly separates it from the read_study_summary sibling, but it never names the alternative, so differentiation is inferred rather than stated.

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

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

'After explicit approval' gives a real precondition, and 'force regenerates unchanged coverage' implies when the force flag is warranted. However, no alternatives are named (e.g. read_study_summary for reading without regenerating) and no when-not-to-use guidance is offered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: it is display-only, the human reviews and responds in chat, and multiple operations render as independent tabs in a single widget.

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

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

A single front-loaded sentence that leads with what is shown and follows with the display-only constraint and tabbing behavior. No filler, though the sentence is dense enough to be slightly hard to parse.

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

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

An output schema exists, so return values need no explanation, and the safety profile is carried by annotations. The description supplies the rendering behavior (tabs, one widget, human-in-the-loop) an agent needs to use it correctly; only explicit sibling routing 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 both parameters are already documented in the schema, including the single-vs-array alternative. The description reinforces 'one or more' operations and the tabbed co-display semantics but adds no format or constraint detail beyond that, so baseline 3 applies.

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

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

States a specific verb+resource — shows source research, distributions, proposed Minds, draft and training for Audience operations — which is far more informative than the title 'Show Audience Creation'. It distinguishes the Audience domain from the sibling render_* tools, though it never explicitly contrasts itself with render_study_plan or render_study_results.

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 'display only: the user confirms or asks for changes in chat' implies this is a presentation step with no mutation, which is useful context. However, it gives no explicit when-to-use guidance against alternatives like get_audience_creation_progress or the other render_* tools, and no prerequisites.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false). The description usefully adds state context that research has not started and that this is a review/confirmation render, but says nothing about what is displayed, whether confirmation has side effects, or any prerequisites.

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

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

Two compact sentences, front-loaded with the verb and resource, with no filler. The state qualifier is placed at the end where it reads naturally, though one could argue it deserves earlier emphasis.

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

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

An output schema exists, so return values need not be described, and annotations carry the safety semantics. Still, with three fully undocumented required params and no differentiation from the neighboring get_study_plan/render_study_results tools, the definition leaves the agent short of what it needs to invoke confidently.

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% across all three required parameters (studyId, draftPlanId, revision). The phrase 'at its current revision' loosely hints that revision selects the version, but studyId and draftPlanId receive no explanation and the constraint that revision must be the current one is left implicit. The description does not compensate for the coverage gap.

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

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

The description gives a specific verb+resource ('Shows a saved Study draft at its current revision') and adds the purpose of interactive review/confirmation. It distinguishes itself from render_study_results by the 'research has not started' framing, though it never explicitly contrasts with the sibling get_study_plan. Minor terminological drift: the tool is named 'plan' but the text says 'draft'.

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?

'Research has not started' and 'for interactive review and confirmation' imply the pre-research review phase, so usage is partially inferable. However, no explicit when-to-use, exclusions, or alternative (e.g., get_study_plan vs render_study_plan vs list_study_drafts) is stated, leaving the agent to guess.

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 non-destructive, so the safety profile is covered. The description adds real behavioral context: it can render a run's finished questions while others still run (partial results), and it imposes a selection constraint the schema omits.

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 capability and followed by the invocation constraint; no filler. The first sentence is dense with parenthetical enumerations but every element is informative.

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

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

An output schema exists, so return values need not be described. For a three-parameter read tool, the description supplies the key constraint and partial-result behavior, leaving only sibling differentiation as 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 0%, so the description carries the burden and largely succeeds: it states that questionId and runId are mutually exclusive and that exactly one is required, and it describes what each selects (one question vs. a run's finished questions). It does not clarify studyId's role or the accepted identifier formats.

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 ('Shows') and resource ('results of finished questions'), and enumerates the returned content (summary, key findings, Audience breakdowns, Mind responses). It distinguishes the two modes (single question vs. a run's finished questions), though it does not explicitly separate itself from sibling tools like read_study_summary or get_study_status.

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

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

'Use it whenever the user asks about results' gives an implied trigger but is overbroad, since siblings read_study_summary and refresh_study_summary also service results requests. No alternatives or exclusions are named, so the agent must infer when this tool is preferable.

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 readOnly=false, idempotent=true, and destructive=false, but the description adds substantive context they cannot: the paid-plan entitlement requirement, the explicit-approval gate, and the preservation semantics ('keeps the originally confirmed questions and response contracts and does not ask questions already answered'). This is genuine behavioral disclosure beyond structured fields.

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

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

Three tight sentences, front-loaded with the core action and followed by preconditions and preservation semantics. No filler and nothing repeated from the schema.

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

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

An output schema exists, so return values need not be explained, and the description covers prerequisites and mutation semantics for a non-read-only tool. It is slightly thin on failure behavior (e.g., what happens when the entitlement is absent), which keeps it from a 5.

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

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

Schema description coverage is 100%, so runId, study (id/name/precedence), and confirmed are already fully documented in the schema. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (Resumes) and resource (plan-limited Study run) with the key qualifier 'in place'. It implicitly routes away from start_study_run by stating it 'does not start a new draft or change the run design,' so an agent can distinguish the two 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?

Gives clear preconditions – an existing stopped run, explicit user approval, and the required paid-plan entitlement. It does not explicitly name the alternative tool (start_study_run) for the create-new case, leaving that routing to inference, which keeps it just below a 5.

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

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

Annotations already flag destructiveHint=true, idempotentHint=false and openWorldHint=true. The description adds real behavioral context beyond them: optimistic-concurrency failure on stale revisions, verbatim preservation of fixed questions when only answers change, bounded-history pruning, and that the changed draft needs re-review. It stops short of describing return/pagination behavior.

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

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

Four short sentences, front-loaded with the action and scope, then preconditions and side effects. No filler; every clause carries a distinct fact an agent needs.

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

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

With rich annotations, 100% schema coverage and an output schema, the description covers the essentials an agent needs (concurrency, side effects, re-review). It could go slightly further on how edits/answers interact, but 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 baseline is 3, but the description adds meaningful semantics for the two identity parameters: draft.id and draft.revision must be the current values and stale ones fail, which the schema does not state. Remaining parameters rely on the schema's own rich 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?

States a specific verb+resource ('Revises one saved draft') and pins the scope to the existing draft.id/revision, explicitly noting it does NOT start research. This cleanly separates it from save_study_draft (exact edits, no model call) and create_study_plan (new draft).

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?

Enumerates the accepted invocation cases ('edits, refinement, clarification answers or response-format corrections') and states the stale-revision precondition, giving clear context for when to call it. It does not, however, name the sibling to prefer for a plain verbatim edit versus a model-assisted revision, so the when-not is left implicit.

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 establish mutation/destructive/non-idempotent behavior, and the description goes further by disclosing partial-update semantics ('Revisions change only the fields given'), optimistic-concurrency enforcement (exact draft ID plus expectedRevision, stale writes rejected), and retry mechanics via idempotencyKey. It does not explain why destructiveHint=true or what can be lost on a stale-overwrite attempt, which leaves one meaningful gap given the destructive annotation.

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

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

Three sentences, front-loaded with the create/checkpoint purpose before revision rules and the retry hint. Each sentence carries distinct information (purpose, revision safety, retry key), though the final sentence is dense and slightly buries the idempotency guidance inside the purpose paragraph.

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. The description covers the create-vs-revise distinction, per-field omission defaults on create versus revision, concurrency control, and retry strategy - everything an agent needs to call this 8-parameter mutating tool 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 the id, idempotencyKey, expectedRevision, mode, methodId, and omission-default semantics are already documented per property; that sets the baseline at 3. The description reinforces the idempotency contract with 'choose before the first save and reuse it after an uncertain result,' which adds a little usage meaning but no format or syntax detail beyond the schema.

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

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

The description gives a specific verb+resource+scope: 'Creates or checkpoints an unfinished Quick or Custom Study draft without starting research.' The phrase 'without starting research' implicitly separates it from create_study, and 'checkpoints an unfinished draft' separates it from create_study's completed-study path. An agent can route between save_study_draft, create_study, and list_study_drafts without opening a schema.

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

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

Clear context is given for both branches: create when no draft ID exists, revise when one does, and idempotencyKey is recommended before a first save and reused after an uncertain result. It never names create_study explicitly as the alternative for starting research, leaving the exclusion implicit rather than stated, so it falls short of full when/when-not/alternatives guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered; the description adds that the created template is private and that template.requestId enables safe retries. That retry/idempotency-key guidance is genuinely useful context beyond the structured fields, though it sits in mild tension with idempotentHint=false (retries are only safe when the caller supplies requestId, not by default).

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 compact sentences: the action leads, the retry mechanism follows, and the exclusions close. No filler, and the most important 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?

An output schema exists, so return values need not be described, and the nested input schema is fully annotated. The description covers purpose, side-effect scope and exclusions adequately; it could go slightly further by naming the sibling to use for draft/modification flows, but 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% and the nested configuration is documented inline, so the schema carries the field-level detail. The description still adds meaning by summarizing the template contents (questions, response settings, attachments, method) and by explaining the purpose of requestId as a retry-safety key, which the schema only calls a 'stable requestId'.

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 a private Custom template') and enumerates the payload it carries (questions, response settings, attachments, method). It also differentiates from siblings by negation ('Does not change existing templates, create a draft or start research'), separating it from update_study_template, save_study_draft and start_study_run.

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

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

It gives clear exclusion guidance — not for modifying existing templates, not for drafts, not for starting research — which implicitly routes the agent away from save_study_draft, update_study_template and create_study/start_study_run. However, it never names those alternatives explicitly, so the agent must infer which tool to reach for instead.

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

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

Annotations already flag destructive, open-world and non-idempotent behavior, and the description adds real value on top: paid-plan gating, "omitting it may replace earlier derived results" (the destructive mechanism), public website visiting, and an approval requirement. It stops short of saying whether the run is asynchronous or what happens to in-flight results.

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

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

Front-loaded with the purpose, then five short clauses that each carry information; no filler or restatement of the title. The telegraphic style is slightly compressed but readable.

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

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

An output schema exists, so return values need no explanation, and the destructive/open-world profile is covered. Still missing for a paid, approval-gated, destructive start operation: what messageId actually is, and how this differs from start_study_run.

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 carries the full burden, yet it explains only assetKey (reuses completed analysis of that asset). The required messageId plus studyId and studyName are left entirely undefined, which is a large gap for a 4-parameter mutation.

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?

"Starts attention analysis of an assigned image, video or website" gives a specific verb (starts), resource (heatmap/attention analysis) and the supported asset types. It does not, however, differentiate itself from the close sibling start_study_run, leaving the agent to infer which entry point applies.

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

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

Preconditions are stated (one response per Mind, paid plan required, explicit approval required) and the assetKey reuse-vs-replace tradeoff is spelled out. What is missing is routing guidance: no mention of when to pick this over start_study_run or how it relates to get_study_heatmap/export_heatmap.

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

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

Goes well beyond the annotations: it discloses atomic all-or-nothing refusal before Minds or quota are consumed, that failures are pre-checked (revision, capabilities, method, source-readability), that Mind answers are sequential and self-visible, that askIf gates items, and that contradictions are flagged rather than rewritten. The idempotent/durable run semantics are spelled out rather than left to idempotentHint.

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

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

Front-loaded with the confirmation gate, and every sentence carries distinct information: atomicity, opt-in, per-Mind ordering, contradiction handling. Slightly over-packed with run-internal behavior that reads like return semantics, but no sentence is filler.

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

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

An output schema and annotations exist, so return values need not be described; the description covers the mutation risk profile (atomic refusal, no quota burn, idempotent retry) thoroughly. It omits how to follow up on the started run (status polling / resume), which would help an agent after 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%, so the baseline is 3; each parameter already carries a description (draft id/revision, study precedence, idempotencyKey for retries, modelConnection pinning). The description reinforces the confirmation gating and advancedMethodOptIn meaning but adds no format, syntax, or selection detail the schema lacks.

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: it 'runs one reviewed draft revision' and submits 'the whole draft as a single durable run', which is far more precise than the title alone. It implicitly separates itself from save_study_draft/revise_study_plan by requiring prior review, but never names the closest sibling (resume_study_run), so an agent must infer the start-vs-resume split.

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

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

Gives a clear precondition and a counter-example: confirmation must come in a later user turn, and 'skipping review is not confirmation'. It also flags that advanced methods need explicit opt-in. It stops short of naming the alternative tool for continuing or polling an existing run.

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

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

Annotations already flag destructive=true, idempotent=false, openWorld=true, but the description adds substantive behavior beyond them: fields are replaced with no restore history, sharing with the team is a possible side effect, explicit approval is required, and stale revisions fail. These are exactly the traits an agent needs before making a mutating call.

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

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

Four tight clauses with zero filler, front-loaded with the core action followed by mutation semantics, side effects, and constraints. Each sentence carries distinct information an agent needs.

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 deeply nested schema and an existing output schema (so return values need no explanation), the description covers purpose, mutation/replacement semantics, concurrency handling, approval requirements, sharing side effects, and an explicit non-goal. Nothing essential for a correct call is missing.

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

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

Schema description coverage is 67%, so moderate compensation is expected. The description names the nested path update.expectedRevision and explains its failure semantics ("stale revisions fail"), which adds real meaning, but templateId and conversationFiles receive no interpretive help beyond the schema itself.

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 ("Updates one owned Custom template") and scopes it to owned Custom templates specifically, which separates it from list/save/use/delete template siblings. The closing clause "Does not start research" explicitly walls it off from the study-run tools (start_study_run, ask_study).

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

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

It gives clear context for use: the template must be owned, it operates at a specific expected revision, and it explicitly excludes starting research. However, no alternative tool is named, so the agent gets an exclusion but not a positive routing rule (e.g., save_study_template for new templates).

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 beyond the annotations by explaining the retry contract ('Reuse use.requestId for retries of the same intended draft'), that the template is left unchanged, and that research does not start. The annotations already flag idempotentHint=true and non-destructive behavior, so this confirms and enriches rather than merely restates, though it omits permission/authorization requirements.

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

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

Three tight sentences with the mutation front-loaded, followed by retry semantics and side-effect clarifications. No filler, though a brief pointer to the relevant sibling would have added value without bloat.

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

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

An output schema exists, so return values need not be described. The description covers the mutation's scope, idempotency/retry behavior, and non-effects ('template is unchanged', 'research does not start'), which is strong for a nested-parameter write tool; only permission/auth requirements are absent.

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

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

With only 50% schema description coverage, the description usefully explains the meaning of both nested fields—expectedRevision as the template revision being acted upon and requestId as a retry-deduplication key. It compensates well for the coverage gap, though templateId itself is left to the schema and obvious naming.

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 independent editable Study draft') plus the source ('from a readable template at use.expectedRevision'). This makes it clearly distinguishable from siblings like create_study (blank study) and duplicate_study (copying an existing study), without needing to name them.

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 workflow context ('Fresh context and Audiences are added in the web app; the template is unchanged and research does not start') but never states when to choose this over create_study, duplicate_study, or list_study_templates. Usage is inferable but not explicit, and no exclusions are given.

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