Minds: Synthetic Market Research

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

Annotations already declare a non-read-only, destructive, non-idempotent, open-world mutation, and the description adds real context beyond that: the Study is private, 'preparing is not question admission', the server may reword context-dependent questions, ambiguous requests return planning_required, and a Study does not start until Minds can read every file. It does not spell out cost/credit consumption for asking a live Audience, which is the main remaining gap for a heavy mutation.

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

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

The out-of-scope rule is well placed and front-loaded, but the opening is dense with terse fragments ('preparing is not question admission', 'Report the current phase from the receipt and progress') whose meaning is not self-evident. Several attachment sentences duplicate schema text word-for-word and could be trimmed.

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

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

For a six-parameter mutation with an output schema, the description covers the essential decision surface: single-question scope, planning fallback, private Study creation, and attachment handling. Return values need not be explained since an output schema exists, leaving only cost/latency expectations 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 every parameter, including the nested attachment objects, is already documented in detail. The description's attachment paragraph largely restates the schema (URL vs Minds upload path, temp/portfolio/context exclusions); the one added nuance is that pasted material belongs in textAttachments rather than the question, which the schema also states.

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: accepts exactly one standalone question for an existing Audience and creates a private Study. It explicitly carves out the multi-question case, so an agent can tell it apart from ask_study / plan_study_questions without opening a schema.

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

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

The 'Out of scope' paragraph states a clear when-not-to-use rule (questionnaire, battery, section, or two or more known questions) and says the alternative is a planned multi-question block inside a Study. Ambiguous or generated questions route to planning_required, which is actionable, though the sibling tool for that path is not 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 destructiveHint=true, idempotentHint=false and openWorldHint=true; the description goes further by disclosing durability semantics ("Durably accepts before execution"), that question text is shown to the Minds and can influence answers, and that fixed time-bucket retries may resubmit so status should be checked. That is exactly the non-idempotent write behavior an agent needs and is entirely consistent with the annotations.

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

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

The purpose and the exclusion come first, followed by behavioral rules, and no sentence is pure filler. Some lines are telegraphic to the point of opacity ("Durably accepts before execution. planning_required requires confirmation."), which costs a little readability but keeps the definition compact.

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, deeply nested mutation with an output schema, the description covers the question contract, evidence handling, confirmation and retry behavior well. Remaining gaps are the missing sibling contrast (ask_audience vs ask_study) and no statement of what Study state must exist before a question can be accepted, both of which the agent would otherwise have to guess.

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 heavy nested objects (model, study, evidence, response, audienceIds, conversationFiles) are already documented. The description adds a useful routing summary — pasted material goes verbatim into evidence.textAttachments and conversation files go to the top-level conversationFiles field — but that restates the schema rather than adding new parameter meaning. 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 and resource ("Requests exactly one respondent-visible question") and immediately bounds the unit of work: one standalone question or one result-dependent adaptive follow-up. The out-of-scope sentence excludes questionnaires, batteries, sections and sets of known questions, so the boundary against batch-style siblings is drawn without the agent opening another schema.

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

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

Gives an explicit when-not (anything with two or more known questions) and a redirect pattern ("use one confirmed block, submitted once rather than question by question"), plus a confirmation rule for planning_required and a retry rule for uncertain writes. It stops short of naming the sibling tools (run_study_questions, ask_audience), so the agent must infer which tool the "confirmed block" refers to and when to prefer ask_audience over ask_study.

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?

Goes well beyond the annotations by disclosing state-dependent timing (queued/preparing stops immediately, being answered stops at the next step), data retention ('Answers given are kept'), and the error behavior for already-answered or failed questions. That is exactly the mutation semantics an agent needs before committing a destructive cancel.

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 action and identifiers, then timing, then data-retention and error behavior. No filler and no repetition beyond what clarity requires.

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. What the description must supply for a destructive, state-transitioning cancel — when it takes effect, what survives, what errors, and what scope is excluded — is all present.

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

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

Schema coverage is 100%, so each parameter already documents its role and how runId relates to studyId/questionId. The description restates that either/or structure compactly and front-loads it, but adds no format, precedence, or validation 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 ('Stops') and a precisely scoped resource ('one standalone Study question'), plus the two keying modes. The closing clause 'Not for multi-question runs' actively separates it from sibling run tools like run_study_questions 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?

Gives an explicit exclusion ('Not for multi-question runs') and points to where the identifiers come from (ask_study / ask_audience). It does not name the sibling an agent should use instead for multi-question runs, so the routing is implied rather than explicit.

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

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

Annotations already declare destructiveHint, idempotentHint and openWorldHint, yet the description adds materially new behavior: the call returns an asynchronous draft/operation rather than a finished Audience, rework overwrites the stored request, roster and grounding in place, and link sharing makes the Audience world-readable without login. Those are operational consequences an agent could not infer from the flags alone.

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

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

Five sentences, front-loaded with purpose followed by the review-then-create condition and the rework rule; no filler. It is dense with schema-specific terms (draft.id/sha256, roster/quota snapshot), which costs a little readability but not correctness.

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 nine-parameter nested tool with an output schema, the description covers the essential lifecycle: async operation, mandatory user acceptance before creation, in-place rework, and the private-by-default posture. Remaining gaps such as plan ceilings and operation polling are delegated to the schema and to get_audience_limits, which is reasonable.

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 carries per-field meaning and the baseline would be 3. The description still earns credit by explaining the lifecycle meaning of draft.id/sha256 ('Rework the same draft.id/sha256 in place... never start a new brief for that edit') and the privacy consequence of the link-sharing flag, tying several parameters into one coherent workflow.

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

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

The description names a specific verb and resource ('Builds grounded Audience/Mind profiles') plus the distinguishing mechanism ('exact segment allocation'), and it separates this tool from a named sibling behavior ('Existing Audiences use recalibration'). An agent can distinguish it from create_study, import_audience_sources, or recalibrate_audience without opening any schema.

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

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

It gives a hard precondition for creation ('create only after the user accepts its roster/quota snapshot and checksum') and routes existing-audience edits to recalibration, which is explicit when-to-use-instead guidance. It stops short of naming import_audience_sources as the route for plain-text grounding, so the alternative set is incomplete rather than absent.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=true and destructiveHint=false; the description goes well beyond them by disclosing atomic rollback of partial Audience failures, that Studies cannot be deleted (extra Studies are permanent), and that link sharing publishes attached Audiences and their Minds at world-readable URLs. The duplicate-name no-op is consistent with the idempotent hint rather than contradicting it.

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 in the first sentence and each subsequent paragraph addresses a distinct decision (duplicates, research routing, atomicity, sharing). It is slightly long and the closing sentence ('does not change or replace an existing Study') partly repeats earlier points.

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

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

With an output schema available, the description needn't explain returns, and it still covers the aspects structured fields cannot: permanence of created Studies, atomic rollback, privacy side effects of link sharing, and duplicate handling. Nothing an agent needs to call this 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 description coverage is 100% and the schema already carries the key per-parameter warnings (including the isLinkSharingEnabled publishing caveat and the audienceIds/audienceConfigs preference). The description adds routing context around allowDuplicateName and multi-question submission but little parameter-level syntax or defaults beyond what the schema documents, 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 ("Creates a Study workspace") plus the two source modes (existing Audiences or inline Audience configurations). It also carves out the boundary against siblings ask_audience/ask_study/run_study_questions by saying it does not ask questions or run research.

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-not guidance (no research inside it; follow-up research in an existing Study needs no new Study), duplicate-name routing (use the existing Study unless allowDuplicateName is true), and a directive that requests with two or more known questions belong in one planned multi-question block. An agent can distinguish this from plan_study_questions and ask_study from the text alone.

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

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

Beyond the annotations it discloses that the result is a non-executing draft, that "Research has not started," that the returned revision "needs review and later explicit confirmation," and that "Saving bounded history may prune older revisions" — a genuine side effect worth knowing given destructiveHint=true. It also explains respondent-level routing semantics for askIf and per-Mind answer isolation. It leaves out the idempotency behavior (that a repeated identical call returns the already-saved revision), which the schema documents but the prose does not.

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 the first sentence, which is good. After that the paragraph becomes a grab-bag: question-count policy, planner mode selection, skip logic, attachment routing, revision pruning, and confirmation state, with the skip-logic sentence ("Each Mind sees only its own earlier answers") dropped in abruptly and relying on unexplained domain jargon ("Mind"). It is dense but not wasteful in wording.

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

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

For a seven-parameter nested tool with an output schema and full schema coverage, the description covers the important qualitative facts: non-executing draft, review required, revision pruning, and attachment-to-question mapping. Gaps remain around lifecycle placement — it never says when to follow with revise_study_plan, save_study_draft, or run_study_questions, nor does it mention conversationFiles or idempotency, which are the two parameters an agent is most likely to mishandle silently.

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 carries parameter meaning and a 3 is the baseline. The description adds only marginal interpretation, such as "With multiple attachments, stimulus.questionAttachments assigns each question; [] means none" and the request/questions distinction. It does not add syntax, formatting, or precedence guidance (for example study id vs. name resolution) beyond what is already inlined in the schema.

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

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

States a specific verb and resource: "Creates a non-executing draft in an existing Study with its Audiences already attached," which is precise enough for an agent to know this is the plan-creation step rather than a run. It also distinguishes its two input modes (request vs. questions). It stops short of naming how it differs from near neighbors like revise_study_plan, plan_study_questions, or save_study_draft, which the sibling list shows are easily confused with it.

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

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

Gives real conditional guidance: "The setup operation for two or more known questions," plus an explicit exclusion that "A one-question draft is only for genuinely standalone research or an adaptive follow-up." It also routes between the two planning modes ("request designs questions; questions preserves a fixed instrument verbatim"). What is missing is direction to the alternative tools — nothing says to use revise_study_plan for an existing draft or save_study_draft for a later step.

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

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

Beyond the destructive annotation, the description adds that deletion is permanent, restricted to templates owned by the authenticated user, and does not cascade to Studies or drafts created from the template. These are meaningful behavioral details for a destructive tool.

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

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

Two tightly written sentences. The scope limitation is front-loaded, followed by the deletion effect and non-cascade behavior, with no wasted words.

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 single-parameter destructive tool with full annotations and an output schema, the description covers purpose, exclusions, ownership, permanence, and downstream effects. Nothing essential 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 parameter already documents that it is the template to delete permanently and is owner-only. The description reinforces ownership but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

The description uses a specific verb-resource pair ('Permanently deletes one template') and explicitly scopes it to saved Study templates. It also distinguishes the target from Studies, Audiences, Minds, and answers, making misuse unlikely.

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

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

It clearly says this is only for saved Study templates and lists the resource types it cannot delete. This provides strong exclusions, though it does not name an alternative tool for those other deletion cases.

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

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

Annotations already flag a non-read-only, open-world, non-idempotent but non-destructive write. The description adds real value beyond that: it discloses that copying can trigger retraining with public web research, that ready copies skip retraining, and that the copy is independent. Permissions (must be able to edit) and allowance impact are left to the schema, which is a minor gap for a write tool.

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

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

Three sentences, front-loaded with the action and scope, then the two conditional behaviors. Dense but every sentence carries behavioral information; only the unqualified jargon ("Minds", "formations", "retained evidence") slightly reduces first-read clarity.

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

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

The tool's complexity is modest (one required param, an output schema, and annotations covering safety and open-world behavior), and the description fills the remaining gap by explaining what gets copied and when retraining occurs. An agent has enough to call it correctly without asking a follow-up.

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 audienceId, name, and idempotencyKey are already fully documented, including defaults and retry semantics. The description adds no parameter-level meaning beyond what the schema provides, which is the baseline-3 case 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 and resource ("Adds an independent copy of an Audience") and enumerates exactly what is copied (its Minds and retained knowledge), so the agent knows the scope of the operation without opening the schema. The Audience resource is unambiguous against the study-oriented siblings such as duplicate_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?

The description describes outcomes for two states (unready copies queue retraining; ready copies avoid retraining) but never states when an agent should choose this tool, nor points to an alternative such as create_audience_from_brief. Usage is only implied by the act of duplicating.

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

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

The description adds useful behavioral context beyond annotations: the copy is permanent, includes questions and results, and keeps the same Audiences. However, it omits permissions, run-state restrictions, and idempotency behavior, which are covered 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 front-loaded sentence communicates the core operation with no filler. It is appropriately compact and easy to scan.

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 definition is reasonably complete given the rich schema and output schema. Minor behavioral details such as live-run refusal and idempotency defaults live in the schema rather than the description, but the core operation is clear.

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 are already documented in the input schema. The description does not add parameter-level meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource: copying a Study, including questions, results, and the same Audiences. It is clear what the tool does, but it does not explicitly differentiate itself from sibling creation or duplication tools.

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

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

There is no explicit guidance on when to use this tool versus create_study, duplicate_audience, or other study tools. The purpose implies duplication, but no alternatives, prerequisites, or exclusions are stated in 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 already flag destructiveHint=true, idempotentHint=false, and openWorldHint=true, but the description adds genuinely new behavior: this kicks off an asynchronous artifact job, force replaces an existing artifact, public HTTPS member portraits may be fetched for brief PDF/PPTX, and slow exports can irreversibly email the requesting account. That last side effect is the kind of non-obvious, irreversible outcome an agent must know before calling. It stops short of saying what specifically is overwritten when force is used.

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, each carrying a distinct fact (what is exported, external portrait fetch, async/force behavior, email side effect), with the core export purpose front-loaded. The construction 'or kind validation_report' is slightly awkward, 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 four-parameter tool with an output schema and rich annotations, the description covers output formats, artifact-job semantics, the force/replace behavior, and the irreversible email risk. The main remaining gap is sibling routing relative to the many other export_* tools, which the description never addresses.

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

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

Schema coverage is 100%, so kind, force, format, and audience are already fully documented with enums and format restrictions. The description's only contributions are that force replaces cached artifact work and a summary of what a validation_report contains, which largely restates the schema. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

States a specific verb (exports) and resource (Audience brief / validation_report) and enumerates the artifact contents and output formats, so the agent knows exactly what it produces. It does not distinguish itself from nearby siblings such as export_study, export_mind, or export_heatmap, leaving the Audience scoping to be inferred from the audience parameter.

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

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

Usage is implied rather than stated: the audience parameter and the kind enum tell the agent this is for Audience artifacts, but there is no explicit 'use this when… use export_study instead when…' guidance. The note about validation reports needing edit access and a scored validation appears in the schema, not as routing guidance in 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?

While the annotation provides a general destructive hint, the description adds necessary detail by stating that 'force starts fresh archive work and replaces its saved artifact status/reference.' This explains the specific behavioral consequence of running the tool.

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

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

The description is perfectly sized, using two highly dense sentences to convey the entire functional scope and major operational constraints. There is zero wasted language.

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?

It is highly complete for an export operation, specifying the contents of the ZIP file (stored screenshots and overlays) and defining the critical state-changing behavior of the 'force' parameter. This is exactly what an agent needs to understand the tool's full utility.

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

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

The input schema coverage is 100%, meaning the schema thoroughly defines the parameters. The description does not need to elaborate on the semantics of messageId or study ID, resulting in a baseline score.

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 immediately states the action (exports), the resource (website heatmap), the format (ZIP of screenshots/overlays), and the required identifiers (Study/message ID). It clearly differentiates this function from simple retrieval operations like get_study_heatmap.

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

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

It provides crucial usage context by explicitly stating that the tool does not perform live website capture. Furthermore, it explains the function of the 'force' parameter, clarifying when it is necessary to 'starts fresh archive work'.

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 it discloses that the call starts asynchronous artifact work, that `force` can destructively replace an artifact, that portrait fetching for PDF/PPTX makes public HTTPS requests, and that slow exports may irreversibly email the requesting account — non-obvious side effects that align with and enrich destructiveHint/openWorldHint rather than repeating them.

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

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

Front-loaded with purpose and format options, and every sentence carries information, though the telegraphic phrasing ("Starts artifact work") costs some clarity that a few more words would fix.

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 covering return values and full parameter descriptions, the description covers the key risk surface — destructive replacement, async completion, and emailing. It omits prerequisites such as what happens when the name does not match or whether a Mind must be shared first.

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 only light meaning (md is returned inline, portraits apply only to PDF/PPTX, force replaces rather than reuses a cached artifact) and leaves the mindId/mindName relationship unexplained.

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

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

The description states a concrete verb and resource ("Exports an existing Mind by ID/name") and enumerates the output modes (inline Markdown default, PDF/DOCX/PPTX), which is enough to distinguish it from the audience/study/heatmap export siblings without opening a schema.

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

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

It establishes the default behavior (inline Markdown unless a format is requested) and when `force` is relevant (replacing an existing artifact), but never states when to prefer this over export_audience/export_study, nor the mindId vs mindName selection rule beyond "ID/name".

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

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

Beyond the destructive/openWorld annotations it discloses genuinely new behavior: the export is queued asynchronously, it returns job/artifact status, full reports can fetch external public HTTPS portraits, and completed exports can irreversibly email the requesting account. The email side effect is a real consequence not captured by any annotation, which is exactly what the description should add.

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?

Semicolon-separated clauses front-load the purpose and then layer formats, return behavior, and side effects with no filler. The telegraphic phrasing ("raw CSV/XLS/SPSS SAV") is compact but slightly compressed for the format list.

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

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

With an output schema present, it needn't document return shapes, yet it still flags job/artifact status, and it warns about the destructive force flag and irreversible emailing for a mutation tool. The main remaining gap is routing among the many export/render 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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema does not: which formats pair with which report kinds (executive/full vs raw data), and that force replaces existing artifacts. It does not cover the scheduledRunId or researchResultId scoping here, but those are well documented in the schema.

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

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

"Queues Study results export" gives a specific verb plus resource, and the format/kinds enumeration (executive/full reports vs raw CSV/XLS/SAV) makes the output space concrete. It never names a sibling, so an agent must still infer the boundary with render_study_results or export_audience.

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

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

The description says what the tool produces but never states when to choose it over alternatives such as render_study_results or export_heatmap, nor any prerequisites. The only selection logic (kind defaults, omitting study to use the active Study) lives in the schema, not in 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 already declare readOnly, idempotent, non-destructive, closed-world, so the bar is lower. The description still adds value: it reinforces 'never starts or retries work' and explains what different status outcomes mean (validation's 10-ready-Mind rule, retained result vs terminal error, and the condition for a final score). This is genuine behavioral context beyond the annotations.

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

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

It is extremely compact with no filler, but the structure is telegraphic and fragmentary ('operationId: creation and member training.' / 'recalibrationId: its status, retained result or terminal error.'). The behavioral line is front-loaded while the actual purpose is buried, making it harder to parse than it needs to be.

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

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

An output schema exists, so return values needn't be re-explained, and all three optional parameters are documented with added meaning. The description supplies the status/condition semantics an agent needs to act on the response. It is only slightly short of complete due to the murky purpose framing.

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 baseline would be 3, but the description goes beyond the schema by mapping each parameter to the distinct progress it reports: operationId→creation/member training, audienceId→training/background research/validation, recalibrationId→status/retained result/terminal error. This adds real semantic value over the schema's terse one-line descriptions.

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

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

The description never states a clean verb+resource sentence like 'returns progress of an audience creation/calibration operation'; instead it opens with a behavioral constraint ('Read-only; never starts or retries work') and dumps per-parameter meanings. The purpose is only inferable by assembling the parameter fragments (creation, member training, validation, recalibration status). It does distinguish itself from mutation siblings, but the core purpose statement is missing.

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?

'Read-only; never starts or retries work' plus 'poll later' and 'add Minds' give meaningful implied usage guidance (this is a poller; when validation.reason=MINDS_TRAINING, call again; when AUDIENCE_TOO_SMALL, change inputs). However, no alternative tools are named explicitly – 'add Minds' doesn't point to a sibling, and the retry path isn't routed to recalibrate_audience by name.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real behavior: limits are live, they override stated limits elsewhere, how the various ceilings govern auto vs. explicit sizing, and that sizes are per-Audience for the account/team named and not a reservation. This is substantive context beyond the structured fields.

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

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

It is front-loaded with the core purpose, but the middle paragraph is dense and heavily qualified (nested ceiling jargon, mode caveats), making it harder to parse than necessary for a simple read-only limits query.

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?

Because an output schema exists, the return values need not be re-explained; nevertheless the description covers the scoping (account/team, not a reservation), the ceilings, and mode behavior, leaving little ambiguity about what the agent will get. It is essentially complete for this tool.

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

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

Schema description coverage is 100% for the single 'mode' enum parameter, so the schema already documents its purpose and omission behavior. The description adds partial semantics by referencing per-mode ceilings and a 'balanced' deeper mode, but does not clarify each enum value, so it only modestly exceeds the schema baseline.

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

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

The description states a specific verb+resource: it returns the authenticated account's plan name, per-Audience size caps (customSizeMax, ceilings), and remaining synthetic responses, read live. This is clearly distinct from sibling list/creation tools and an agent can identify it as the limits-lookup tool immediately.

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 meaningful routing context by stating the values are 'read live' and that it 'supersedes limits stated elsewhere', steering the agent to trust this tool over other sources. It stops short of explicitly naming sibling alternatives or exclusions, but the context for when to call it is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real value by disclosing that cross-workspace public shares are included and that no network fetch happens, but it stops short of describing result shape or any visibility edge cases beyond the share-ID scope.

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

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

Two short sentences with zero filler; the positive scope is front-loaded and the negative constraints follow as a compact caveat. Nothing repeats structured fields verbatim.

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 one required parameter, full schema coverage, complete annotations and an output schema, the description supplies the scope and the two boundary conditions an agent needs. It is nearly complete; only the absence of routing guidance against sibling tools 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 coverage is 100% and the shareId property description is unusually rich (UUID from /minds/shared/{shareId}, not the Mind ID, must be public or link-enabled, excluded fields). The description only echoes 'by share ID' and 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 and resource ('Returns stored public Mind sources/assessments') plus the keying mechanism (share ID) and a scope qualifier (includes shares outside the private workspace). No sibling tool covers the same resource, so an agent can distinguish it without further reading, though the description never names a contrasting sibling.

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

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

Usage is implied by the scope statement and by the two exclusions ('Does not fetch source websites or modify knowledge'), which help an agent rule this tool out for live-site retrieval or writes. It never states when to prefer it over an alternative or what precondition must hold, leaving the agent to infer 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 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 safety profile is covered and the description's "creates or changes nothing" is largely redundant. It does add two facts beyond annotations: that the read returns the latest revision (versioning behavior) and that no research is kicked off. Missing is any note on error behavior for a stale or invalid draftPlanId.

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 the retrieval behavior front-loaded and the non-mutation guarantee second. The second sentence partly restates the annotations, but it functions as a routing signal, so it earns most of its place.

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

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

For a two-parameter, fully documented read tool with an output schema and complete annotations, nothing essential is missing. The only gap is the absence of guidance on which sibling to use for rendering or revising versus reading, which context makes relatively low-risk.

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

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

Schema description coverage is 100%, including the nested study object with id-precedence and active-Study fallback rules, so the schema carries the parameter burden. The description only echoes "one draft," adding no syntax, identifier format, or scoping detail beyond what the schema states. 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?

Names a specific verb ("Reads") and a specific resource ("the latest saved revision and full review of one draft"), so an agent knows this retrieves an existing draft plan rather than producing one. It does not explicitly name siblings such as render_study_plan or list_study_drafts, so differentiation is implicit 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?

"Creates or changes nothing and starts no research" gives a useful negative boundary that rules out mutation and run-start variants, implying this is the pure retrieval path. However, it never positively says when to pick this over render_study_plan or list_study_drafts, leaving the alternative selection 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 mark this read-looking tool as destructiveHint=true and non-readOnly, and the description actually accounts for that: result reads "can queue recovery and overwrite stale derived analysis from accepted answers, without rerunning respondents." That is genuine side-effect disclosure the annotations alone would not explain. It also notes in-flight questions report zero answered until complete. It does not state permission requirements or the cost/latency of triggering recovery, keeping it below 5.

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

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

It is front-loaded with the return content and mode selection, but the sentences are heavily compressed and stack multiple clauses, and fragments like "Export-only polling reads its job." are telegraphic enough to require re-reading. Jargon such as "requestPreparations" is used without definition, so density costs clarity rather than buying it.

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

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

An output schema exists, so return-value explanation is not owed, and the description still covers all three scoping modes, the export polling case, and the in-flight zero-answer edge case. Since the destructive hint is non-obvious for a status tool, a fuller statement of what is overwritten and whether recovery is retryable would close the remaining gap.

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

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

Schema coverage is 100%, so baseline is 3, and the description adds a mutual-exclusion/precedence rule the schema never states: questionId and runId select different scopes, otherwise the Study-wide view applies. It also pins questionId to the ask_study/ask_audience receipt and warns that operationId is a different identifier. Remaining param details (study, export.kind/format/jobId) are left to the schema.

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

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

The description opens with a specific verb and enumerated resources: "Returns Study progress, Audience results, Mind responses and export status in the Study display locale." It then distinguishes the three selection modes (questionId, runId, Study-wide), which separates it from siblings like render_study_results or read_study_summary. It falls short of 5 because phrases like "durable request preparation" and "requestPreparations" are undefined jargon that blur the exact resource being returned.

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?

Selection rules are stated explicitly: questionId for a question or preparation, runId for a confirmed run, neither for the Study, and export polling for a job. That is real routing guidance rather than implied usage. It stops short of naming concrete alternatives for overlapping needs (e.g., render_study_results, read_study_summary), so the agent must still infer when this tool is the wrong choice.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and openWorldHint=true, but the description adds real value: retry semantics for identical imports, the fact that nothing is created downstream, and that supplied percentages are not independently verified. The binding order (existingFiles then files by sourceIdx) is a behavioral detail an agent needs that annotations cannot express.

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

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

Four sentences, front-loaded with the core action and modality before the grounding and safety caveats. The grounding sentence is dense and leans on schema jargon (sourceIdx) that is only defined in the parameter help, 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 exists, so return values need not be described, and the description still flags the normalized snapshot and checksum that come back. For a four-parameter import with side-effect ambiguity, it covers the safety profile and binding semantics; only edge cases (item/size limits, empty-file behavior) are left to the schema.

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

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

With 50% schema coverage, the description compensates well: it clarifies that file content is passed inline, that groundingJson is the distribution object rather than respondent rows, and it spells out the source binding order across existingFiles, conversationFiles and files. It does not explain the 20-item or 5MB limits, but those live in the schema.

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

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

The first sentence names a specific verb (imports) and resource (UTF-8 text, Markdown, CSV and JSON research files) plus the destination (account-owned storage). It also pins down the input modality ('accepts file contents rather than local paths'), which separates it from path-based or audience-creating siblings like create_audience_from_brief.

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

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

It states the call is safe to retry when files are identical, that grounding JSON is optional, and explicitly bounds scope ('creates no Audience or Minds', 'performs no web search or independent verification'). It stops short of naming a specific alternative tool to use when the intent is actually audience creation, so the when-not is implied rather than routed.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real value beyond them: newest-first ordering, the fact that links and commercial details are omitted when addOnRequired, and the distinction between workspaceUrl (owner's workspace) and sharedAudienceUrl (public). The opening link-formatting instruction is useful but makes the behavior harder to parse.

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 badly front-loaded: it opens with a link-text formatting rule rather than stating what the tool does, so an agent must read several clauses before learning the purpose. The remainder is a dense run-on of otherwise useful facts that would benefit from being ordered purpose-first, then parameters, then edge cases.

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, yet the description still usefully flags what fields mean and when links are omitted, plus pagination behavior. For a read-only list tool with four optional params, an agent has what it needs to call it correctly.

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

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

Schema coverage is 100%, so limit, offset, searchQuery and includeMinds are already fully documented in the schema, including defaults, max and nextOffset continuation. The description largely restates them ("limit defaults to 20", "includeMinds adds members", "searchQuery matches names case-insensitively") without adding format or edge-case 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 second sentence gives a specific verb and resource: "Lists the authenticated user's Audiences newest first, with Mind counts, sharing and links." That is clear enough to act on, but it is buried behind a reply-formatting instruction, and nothing distinguishes it from siblings like list_studies or list_study_drafts.

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

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

There is conditional guidance: "addOnRequired means unavailable under current entitlement... use an available Audience" and a first-page hint to rework a draft or recalibrate before starting a new brief. However, there is no statement of when to call this versus list_studies or list_study_drafts, and 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 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?

The annotations declare destructiveHint=true and readOnlyHint=false, but give no explanation; the description supplies the missing why — 'Listing provisions starters or overwrites eligible untouched older starters' — and scopes the blast radius to 'eligible untouched older starters'. It also states the exception ('Exact-template reads skip provisioning'), which is precisely the behavioral nuance no annotation conveys.

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

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

It is front-loaded with the listing behavior before the templateId exception, and each sentence carries distinct information about mode, return shape, or side effect. It is dense and term-heavy ('starters', 'the fixed instrument') to the point of mild ambiguity, and the configuration.questions/methodId sentence sits awkwardly in a listing tool's 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 values need not be explained, yet the description still names the key fields returned by templateId — useful, if slightly redundant. The main unresolved gap is what 'starters' and 'eligible untouched older starters' concretely mean, and searchQuery's behavior is left entirely to the schema; for a tool with a destructive listing side effect, one clarifying clause on eligibility would close the loop.

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

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

Schema coverage is 100% and each parameter is described, so the baseline is 3. The description adds genuine meaning beyond the schema for templateId (full configuration, revision, questions, response settings, attachments) and frames configuration.questions as the 'fixed instrument' and configuration.methodId as the method it runs with, which clarifies return-shape semantics rather than argument syntax. It says nothing extra about limit, offset, or searchQuery beyond what the schema already states.

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 clause gives a specific verb plus resource and scope ('Lists owned/team-shared template summaries, most used first'), then immediately distinguishes the two modes: summary listing vs. 'templateId returns full configuration...'. An agent can tell what this tool does and that it has a dual read shape 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 clearly states the condition that selects each mode ('templateId returns full configuration', 'Omit to list template summaries') and notes that exact-template reads skip provisioning. The gap is sibling routing: it never points to use_study_template, save_study_template, update_study_template, or delete_study_template for the adjacent template lifecycle operations, which is where an agent is most likely to hesitate.

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?

The annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=true and idempotentHint=false, and the description adds only the deprecation status plus the claim of behavioural parity with the successors. It does not explain what a 'plan' block mutates or destroys, nor what the alias changes relative to create_study_plan, so value beyond the annotations is thin.

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

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

A single short sentence with no filler, and the most decision-relevant fact (deprecated alias) is front-loaded. It is efficient, though the brevity reflects missing content rather than disciplined compression.

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

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

For an eight-parameter, destructive, open-world mutation tool with near-zero schema documentation, one line of prose is far from sufficient. An output schema exists so return values need not be explained, but inputs and side effects remain entirely opaque.

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

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

Schema description coverage is 13% and eight parameters (draft, study, policy, request, stimulus, questions, idempotencyKey) are declared with empty schemas. The description supplies no meaning for any of them, leaving an agent unable to construct a valid call from either structured data or prose.

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 identifies the tool only by relation to siblings ('deprecated alias of create_study_plan and revise_study_plan'), so an agent can place it in the family but is never told directly what operation it performs. The 'identical behaviour' clause helps, but the actual verb+resource is borrowed from other tools rather than stated.

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

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

It clearly signals deprecation and names the two replacement tools, which is exactly the routing information an agent needs to avoid this tool. It stops short of saying how to choose between create_study_plan and revise_study_plan, so the alternative selection is only half specified.

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 destructiveHint=true, and the description backs that up concretely rather than contradicting it: it discloses that reads can queue recovery and overwrite stale/missing derived summaries, and bounds the blast radius with 'never reruns respondents'. What it omits is when the overwrite actually triggers and whether any permission is required.

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 return payload before the side-effect caveats. Dense but every clause carries information; only 'refresh receipt' and 'respondents' assume internal vocabulary an agent may not share.

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

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

An output schema exists, so return values need not be spelled out, and the description covers the surprising part of this tool: that a nominally read operation can mutate derived state. The remaining gap is routing relative to refresh_study_summary, which matters because both tools appear to touch summary freshness.

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

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

Schema description coverage is 100%, and the schema already explains id precedence over name and the omit-to-use-active-Study behavior. The description adds nothing about how the study reference affects behavior (e.g. whether a name lookup can be ambiguous), so the baseline 3 applies.

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

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

The description uses a specific verb ('Returns') and enumerates the exact payload: whole-Study Markdown, evidence, generation state and the caller's refresh receipt. That is far more precise than the name alone. However, it never distinguishes this tool from the sibling refresh_study_summary, whose territory ('queue recovery and overwrite stale/missing derived summaries') this description partially claims.

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

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

Usage is only implied: read the saved summary, and use it when derived summaries are stale or missing so recovery can be queued. There is no explicit when-to-use / when-not statement and no pointer to refresh_study_summary or render_study_results as alternatives, which is a real risk given how closely this overlaps with a refresh 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 flag destructiveHint and openWorldHint, and the description goes well beyond them: asynchronous semantics ('the result is an accepted operation with its id, not a completed change'), queueing behind another edit and behind a running Study, shared-Mind copy-on-write behavior with the `allowSharedMinds` override, and requestKey-based safe retry. It also names the failure mode and its retry path (`AUDIENCE_EDIT_UNREAD`). The requestKey retry note is not a contradiction of idempotentHint=false, since it only holds for identical input under the same key.

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 and every sentence carries operational weight: identity preservation, mode coverage, permissions, async contract, side effects, retry. It is dense and partly duplicated by equally rich schema descriptions (deepen/distributions behavior appears in both), and the long parentheticals slow scanning, but there is no filler.

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

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

For a destructive, async, open-world mutation with an output schema, the description supplies exactly what the structured fields cannot: what happens to members and Minds, what is copied versus mutated, how progress is followed (get_audience_creation_progress), and who may call it. Nothing an agent needs before invoking is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still earns above that by tying each mode to the parameter that triggers it (`distributions` for exact chart selection, `deepen` for going deeper) and by flagging the case where `requestedDistribution` is allocated in place of an existing chart with incomparable brackets. It does not restate the heaviest semantics — the `instruction` reach taxonomy — because the schema already carries it.

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

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

The opening sentence gives a specific verb and resource plus the key invariant: 'Changes an existing Audience in place: it keeps its id, its Minds keep theirs ... and no Mind is deleted.' It then enumerates the covered change modes (composition/trait edit, population pivot, additive members, exact `distributions` selection, `deepen`, research re-grounding), which lets an agent separate this from create_audience_from_brief, duplicate_audience, and import_audience_sources without opening a schema.

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

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

It states explicitly when to use it versus an alternative ('Use this, not query, to adjust the Audience'), records the mode exclusions ('Not combinable with distributions, query or requestedDistribution' on `deepen`), and spells out the authorization gate plus staff exclusions ('Staff support is limited to composition amendments: no growth, new sources, Go deeper or shared-Mind waiver').

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, the description discloses exactly what is destroyed: the saved summary is replaced without restore history while questions and answers remain. It also explains the background/pending receipt behavior and the force condition, which are important behavioral details for a destructive async operation.

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

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

The description is front-loaded with the action and approval requirement, then covers destruction, force, and return behavior in compact sentences. Every clause adds useful information without 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 destructive, asynchronous, nested-parameter tool with annotations and an output schema, the description covers approval, destruction scope, force behavior, and pending receipts well. It is slightly incomplete on study selection and length semantics, but those are partly covered by the schema.

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

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

Schema description coverage is 75%, so the schema already documents most parameters. The description reinforces force and approval semantics but does not add meaning for the study id/name selection or the length enum beyond what the schema provides.

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

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

The description states a specific verb and resource: it refreshes a whole-Study summary. It makes the scope clear through 'whole-Study summary refresh' and distinguishes refresh from read by describing replacement behavior, but it does not explicitly name the sibling read_study_summary.

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

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

It gives a clear prerequisite: an explicit approval is required, and it explains that force is for unchanged coverage. However, it does not say when to use this instead of read_study_summary or other study tools, and it 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 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?

The annotations already establish that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds meaningful state context beyond that: the draft is saved, shown at its current revision, intended for interactive review, and research has not started.

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 are front-loaded with the main action and state. There is no filler, and the key constraint that research has not started is placed clearly at the end.

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 annotations and output schema reduce the need to explain safety and return values, and the description covers the review-state context well. However, for a tool with three opaque required identifiers, it is incomplete because it does not explain the parameters or how they relate to the draft revision.

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

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

Schema description coverage is 0% and there are three required parameters, so the description needs to compensate but mostly does not. It alludes to a revision, but gives no meaning for studyId or draftPlanId and does not explain how the revision relates to the saved draft.

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

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

The description states a specific action and resource: showing a saved Study draft at its current revision for interactive review and confirmation. It is clearer than a generic 'render' description, but it does not explicitly distinguish itself from close siblings such as get_study_plan or revise_study_plan.

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

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

It gives a clear usage context: interactive review and confirmation of a saved draft while research has not started. It does not explicitly say when to use this instead of get_study_plan or revise_study_plan, so it stops short of full alternative guidance.

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

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

The annotations already flag destructiveHint=true, and the description earns credit by specifying exactly what is mutated: it queues recovery and overwrites stale derived results from accepted answers. The clarifying clause that it does not rerun respondents is genuinely useful scope information. It stops short of saying whether the overwrite is reversible or what authorization is needed.

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

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

Two tight sentences with the primary capability front-loaded and side effects second. Some domain jargon ('Mind responses', 'Audience breakdowns') is dense but consistent with the product vocabulary used across sibling tools.

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 mutation side effects are well covered. What remains missing for a three-parameter mutation tool is any parameter-level guidance and any signal of when this is the right tool versus the adjacent summary and status 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 0% across three parameters, so the description must compensate and largely does not. It implies run-level and question-level filtering through 'question/run results', but says nothing about how studyId, runId and questionId scope the output, whether runId defaults to the latest run, or what questionId narrows.

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

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

The description names a specific verb ('Shows') and enumerates concrete resources: question/run results, summaries, Audience breakdowns and Mind responses. It is clearly a results-rendering tool rather than a planning or run-control one, but it never names the neighboring tools it could be confused with (read_study_summary, refresh_study_summary, 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?

Useful scoping hints are present ('including partial runs', 'does not rerun respondents'), which tell the agent this works on already-collected data. However, there is no explicit statement of when to choose this over read_study_summary or refresh_study_summary, nor any prerequisite about when a run must exist first.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, and the description usefully reinforces the idempotent 'in place' semantics plus preservation of confirmed questions and response contracts. It does not explain why the operation is destructive (quota/plan consumption) or what side effects occur, which is the remaining gap against the annotation profile.

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, each carrying distinct information: what it does, preconditions, and what it does not do. Front-loaded and free of 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?

With an output schema present, return values need not be described, and all parameters are documented in schema. The description covers preconditions and preservation behavior; only the destructive/cost implications of resuming are left implicit.

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

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

Schema coverage is 100%, so runId, study, and confirmed are already fully documented, including precedence of id vs. name. The description adds only the general framing of resuming an existing run, not per-parameter meaning, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Resumes an existing plan-limited Study run in place') and immediately differentiates from start_study_run by saying it 'does not start a new draft or change the run design.' The agent can distinguish resume-in-place from create/start without opening the schema.

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

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

Gives real preconditions: explicit user approval and required paid-plan entitlement, and scopes usage to an existing stopped run. It also implies the alternatives it is not (new draft, design change), though it never names a sibling tool directly, keeping it short of a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, yet the description adds concrete behavior the agent could not infer: optimistic concurrency ('stale revisions fail'), a data-retention side effect ('Bounded history may prune older revisions'), and a workflow consequence ('the changed draft requires review again'). It also states a preservation guarantee ('Fixed questions stay verbatim when only clarification answers change'), which is exactly the kind of non-obvious contract an agent needs before mutating a draft.

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

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

Five short sentences, front-loaded with the action and its addressing keys, with no filler. The clause listing accepted change types mildly duplicates what the nested schema already documents, which is the only slack.

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

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

For an 8-parameter, deeply nested mutation tool with an output schema, the description covers the important non-schema facts: revision staleness, history pruning, verbatim preservation of fixed questions, and the re-review requirement. It omits run-mode interactions and the study/policy scoping behavior, but those are documented in the schema itself.

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 carries the parameter burden and 3 is the baseline. The description adds one meaningful semantic point beyond the schema, that draft.revision must be the current revision or the call fails, but says nothing about study scoping, policy, or idempotencyKey behavior.

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 ('Revises one saved draft') plus the addressing keys (draft.id and draft.revision) and the negative scope ('without starting research'), which separates it from run_study/start_study. It does not name or differentiate itself from the closely related siblings save_study_draft or create_study_plan, so the boundary with those tools is left implicit.

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

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

It enumerates the four input modes it accepts (edits, refinement, clarification answers, response-format corrections), which is useful selection guidance among its own parameters. However, it never states when to use this tool versus save_study_draft or create_study_plan, and gives no prerequisites or exclusions beyond 'stale revisions fail'.

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

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

Annotations declare destructiveHint=true, openWorldHint=true and idempotentHint=true; the description adds no behavioural detail about what the destructive action affects, whether confirmation is required, or what the open-world interaction touches. "Identical behaviour" is a cross-reference, not a disclosure, so beyond the annotation profile the description contributes almost nothing.

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

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

A single front-loaded sentence with zero filler; the deprecation notice and the behavioural equivalence are both stated immediately. Nothing can be trimmed without losing either signal.

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 tool with 8 undocumented parameters (and an output schema it need not explain), one sentence about being deprecated is thin. It omits any safety context around the destructive run, what the confirmed/audienceIds inputs mean, and why this entry point still exists.

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

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

There are 8 parameters with 0% schema description coverage and no enums, so the description carries the full burden of explaining draft, study, confirmed, audienceIds, idempotencyKey and modelConnection. Saying behaviour is identical to start_study_run implies the parameters mirror that tool, which is a useful pointer but no actual semantics are supplied.

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

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

The description identifies exactly what the tool is (a deprecated alias of start_study_run with identical behaviour), which is precise enough for an agent to know it duplicates a named sibling. It stops short of stating the underlying operation (starting a study run over a confirmed question block), so the agent must consult start_study_run to learn the actual verb+resource.

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?

"Deprecated alias" plus "identical behaviour" is a clear, actionable routing signal: prefer the canonical tool. It does not state whether any caller must still use this name for backward compatibility, nor does it name the replacement with an explicit 'use X instead' directive, leaving a small gap.

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 substantive behavior beyond the annotations: revisions are partial ('change only the fields given'), require draft ID plus expected revision, and stale writes are rejected, plus per-key retry semantics for creation. It does not explain the destructiveHint=true flag — an agent might read the partial-update rule as non-destructive, so the one annotation that signals risk is left unaddressed.

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

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

Four sentences, front-loaded with identity and scope, then persistence, then revision safety, then retry mechanics — a sound ordering with no filler. Dense but every sentence carries distinct information; only slight cost is the packing of three separate rules into the last two sentences.

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

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

For an 8-parameter nested mutation tool with an output schema and annotations, the description covers what an agent needs: create vs revise, partial-update semantics, optimistic concurrency, and idempotency for retries. Return-value explanation is correctly omitted since an output schema exists.

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

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

Schema coverage is 100%, so baseline would be 3; the description earns above that by tying the draft/expectedRevision pair to a concurrency guarantee and explaining the create-vs-revise split of the draft object. It does not add field-level meaning (name, audienceIds, conversationFiles are left entirely to the schema).

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

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

States a specific verb pair and resource: 'Creates or checkpoints an unfinished Quick or Custom Study draft', and immediately scopes it with 'without starting research', which separates it from create_study and start_study_run. The enumeration of what is persisted (objective, context, Audiences, method, questions, sources, planner step) makes the boundary unmistakable.

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

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

Gives clear situational guidance: use it for drafts before research starts, and use idempotencyKey for a retryable creation ('choose idempotencyKey before the first save and reuse it after an uncertain result'). It does not explicitly name the alternative to pick when the user does want to launch research (create_study), leaving that contrast implicit rather than spelled out.

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

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

Annotations already declare readOnlyHint=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 declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the agent knows this is a mutating, repeatable, potentially destructive operation. The description adds essentially nothing beyond that: it does not warn that disabling a link breaks an existing shared URL, that team sharing sends no invitation, or that Audience marketplace listing is unaffected — all of which appear only in the parameter schema. With annotations already covering the safety profile, this sentence adds minimal new behavioral context.

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

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

A single front-loaded sentence with no filler and no redundancy. It is efficient, though bordering on under-specified rather than merely concise — the whole definition is one clause.

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

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

A rich schema, full annotations, and an output schema relieve the description of much of its burden, and sharing toggles are conceptually simple. Still, for a destructive, open-world mutation with five parameters and nested object selection, the description omits who is permitted to call it and what observable effect toggling has on existing recipients. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so every parameter including the nested study/audience id-or-name objects is fully documented in the schema, which sets the baseline at 3. The description contributes no additional parameter meaning; it only implies the link/team toggles exist without naming them or explaining the 'send link, team or both' combination rule. Baseline 3 is therefore correct.

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 ('turns ... on or off') and names both resources (Study, Audience) plus both sharing channels (public link, team sharing). It is clear and distinguishes the tool from any sibling, since no other tool touches sharing state. It stops short of a 5 because it never contrasts itself with adjacent tools like update_item or the listing tools, though none of them overlap meaningfully.

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

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

The description offers no when-to-use guidance, no prerequisites, and no alternatives. It does not say that only the owner may change team sharing, that an owner/admin role is required, or what to do when both link and team need updating. The schema parameter text carries some of this, but the description itself supplies no routing or precondition information.

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.