CrowdOS

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

With no annotations, the description carries the full burden and does so: it discloses pricing (10 free questions then per-question charge), org-level billing exemption, the 3-free-question Deep Review variant, the insufficient_funds error and required user messaging, and the aggregate/no-individual-quotes constraint on answers. This is exactly the cost, failure, and output-shape information an agent needs before invoking a billable 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?

Four tight paragraphs that are front-loaded with the core purpose and then layered by eligibility, pricing, and return shape. A few phrases repeat ('as on the web', the Deep Review pricing restated) and the returns line duplicates information the agent could infer, keeping it just short of a 5.

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?

No output schema exists, yet the description specifies the returned fields (sim_id, answer, chat, charged_credits, questions_remaining_free, credits_per_question) and the two chat modes. Combined with the error list and billing rules, an agent has everything needed to call this correctly and to explain the result to a user.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: sim_id must be a *completed* study of a supported type (with the supported set enumerated), and the question length limit differs for Deep Review screenings, which is also noted. Only minor duplication remains.

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 ('ask a follow-up question about a completed study') and immediately scopes it as the study's moderator chat answered from the study's own results, not a new data collection. It is clearly distinguishable from siblings like run_focus_group, run_debate, and screen_creatives, which are named as the tools that produce the studies this one queries.

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

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

Explicitly enumerates where it works (Pulse studies from run_focus_group/run_debate, Screening Room Deep Reviews) and where it does not (compares, Quick/Balanced screening, Ads Labo, pricing, MaxDiff), including the exact failure mode error='not_supported' with no charge. It also routes Deep Review follow-ups to the analyst chat, giving the agent a clear alternative path.

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

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

With no annotations provided, the description carries the full behavioral burden and does so well. It discloses the refund side effect, the 409 behavior for already-terminal simulations, the fact that closing the session does not stop the run, and the special re-run refund behavior with results_kept: 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?

The definition is front-loaded with the action and refund effect, then uses a short bullet list for usage conditions and a compact paragraph for edge cases. Every sentence adds operational value and there is no wasted prose.

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

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

For a single-parameter cancellation tool with no annotations or output schema, the description is complete enough. It covers the action, side effect, session-close misconception, error behavior, and re-run results behavior, leaving no major ambiguity for correct invocation.

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

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

The schema has 100% description coverage and already documents sim_id as the running simulation id. The description reinforces that the target is a running simulation but adds no syntax, format, or validation detail beyond the schema, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: cancel a running simulation and refund the wallet reservation. It also distinguishes this explicit cancellation from merely closing the MCP session, which is a critical scope distinction.

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

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

It gives explicit when-to-use scenarios such as user changes their mind, wrong parameters, or a debate going off the rails. It also gives a clear when-not-to-use warning: closing the session does not cancel, and the tool should only be called if the user genuinely wants to stop the run and refund credits.

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?

No annotations, so the description carries full burden and does so: it discloses wallet billing at per-respondent rates, plan-based caps on respondents and option counts, and the full return shape including breakdowns and undecided handling. It even warns about the conditions under which results mislead.

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, then clearly sectioned (RECOMMENDED FLOW, plan limits, alternatives, Returns, WHEN IT MISLEADS). The Returns block is long but earns its place since no output schema exists; some prose 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?

With no output schema, the description supplies the return contract in detail (leaderboard fields, breakdowns, undecided, billing) plus cost and plan constraints. An agent has everything needed to call it and interpret results 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 baseline is 3, but the description adds real meaning: image_url vs screen_creatives routing, undecided_option's default-on-for-elections behavior and its output effect, and previewing custom_audience with estimate_reach. It leaves some params (language, topic) to the already-rich 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?

Specific verb+resource: 'Run a simulated A/B (or A/B/C…) test (a Pulse compare) on text options' plus exactly what comes back (leaderboard with Borda scores and winner). It explicitly distinguishes itself from sibling tools screen_creatives (videos/images as creatives) and test_ads (in-feed ads).

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?

Provides an explicit RECOMMENDED FLOW (list_demographic_presets → preview_cost → confirm → run) and names alternatives with the conditions that select them (screen_creatives for videos/image creatives, test_ads for feed ads). It also gives a WHEN IT MISLEADS section describing misuse conditions.

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

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

With no annotations provided, the description carries the full burden and does well: it discloses that the endpoint is public with no API key required, that data is sanitized of internal IDs, and that it draws from a persistent (not one-shot) population. It omits freshness/rate-limit behavior, which keeps it from a 5.

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

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

Purpose is front-loaded in the first sentence, followed by usage context, an auth note, and a compact returns block. Every sentence carries information, though the returns enumeration is dense and could be trimmed if an output schema existed.

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?

There is no output schema, but the description compensates with an inline 'Returns' shape covering population totals and per-agent fields. Combined with the public-access note and sanitization disclosure, an agent has enough to call and interpret it correctly.

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

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

Schema description coverage is 100%, so the lone 'limit' parameter (range 1-60, default 20) is fully documented in the schema. The description adds no additional meaning about sampling size or its effect, 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?

The description names a specific verb and resource ('Browse the persistent CrowdOS crowd — a sample of the live agent population') and adds a distinguishing property (sanitized of internal IDs). It does not explicitly contrast itself with siblings like list_demographic_presets or estimate_reach, so it stops short of a 5.

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

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

It offers a soft use case ('useful for showing what kind of people are in this audience to a user') but gives no when-not guidance and does not name an alternative sibling for related needs such as demographic enumeration. Usage is implied rather than prescribed.

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

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

With no annotations, the description carries the full burden and does so: it discloses cost behavior (no model calls, no wallet debit), latency (under a second), the error contract (audience_size=null plus spec_errors/spec_error_details with the same stable codes a run would reject with at 422, before any charge), and the return shape including audience_note/incidence semantics. It also pre-empts a likely agent misread — that 'small' means blocked — which is exactly the non-obvious behavior an agent needs.

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 free/sub-second hook, then the small-audience caveat, then the returns block and error contract — a sensible order. It is long and partly duplicates the targeting schema's prose about small audiences, but nearly every sentence carries decision-relevant information, so the bulk is defensible.

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?

No output schema exists, so the description supplies an explicit Returns block (audience_size, narrowed_by, narrowing_filters, preset_key, optional by_dimension) and the full failure surface with error codes. Combined with nested-object targeting params, an agent has everything needed to call it, interpret results, and act on failures without guessing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: the preset_key/demographic_preset aliasing rule (send either; both must name the same market), and the critical interest-tag guidance that a ~200-topic taxonomy means a single tag is a narrow slice and several tags are OR-matched. It does not explain sample_size or include_by_dimension's cost/effect beyond the schema text.

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 — preview how broad an audience a `custom_audience` filter describes — and immediately scopes it as a free, sub-second validation step distinct from a paid run. An agent can distinguish it from `crowd_sample`, `preview_cost` and the run tools 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?

Explicit timing is given: 'Call it before a run that uses custom_audience to check the spec is valid and to see how tight the cut is,' plus a strong when-not: never abandon a run because the band returns 'small'. It routes to sibling concepts ('the run tools', fix the spec here before a 422) but never names `preview_cost` or `list_demographic_presets` as alternatives, leaving some inference about which free pre-flight check to pick.

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

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

With no annotations, the description carries the entire burden and does so well: it enumerates conditional return fields, explains that payment_overdue/card_required/credit_line_reached appear only in specific org states, and clarifies that 'while scheduled, studies run until pause_at' with a directive to tell the user to pay or save a card. These are non-obvious behavioral and remediation details an agent could not infer elsewhere.

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

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

Front-loads purpose and usage in two short sentences before the return-field block, and every sentence earns its place by naming a field or a conditional state. The dense parenthetical field list is long but is genuine specification rather than 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?

There is no output schema, so the description must document the return shape, and it does so thoroughly, including conditional-field presence rules and the actionable 'pay or save a card in the organization portal' instruction. Nothing an agent needs to interpret the response or act on it is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The description instead spends its budget on return-value semantics, which is the right use of space for a no-arg tool.

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 resource ('the account's balance') with concrete scope ('what is left, the plan, and who pays for the next study') and adds organization-credit behavior for org members. It is clearly distinguishable from the cost-estimation sibling preview_cost by framing itself as the balance/wallet view.

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

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

Gives explicit triggering contexts: 'before a large study, or after an insufficient_funds error', plus the useful note that it is Free. It does not name a sibling alternative (e.g., preview_cost) for the pre-study case, so routing is clear but not fully comparative.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses cost (free), an authentication prerequisite (signed in as the account that ran the study), and the key behavioral limitation that MCP returns text, so this yields a link rather than a file. It does not describe what happens for an invalid or unknown sim_id, which is the main remaining gap.

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

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

The lead sentence front-loads the tool's job and the return payload, and the mode-by-mode PDF table is useful, non-redundant information. It is slightly repetitive: the 'choose PDF / gives the link, not the file' idea is stated twice.

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?

There is no output schema and no annotations, so the description must supply the return shape and the behavioral contract itself. It lists the returned fields (sim_id, status, mode, results_url, pdf_available, pdf_note) and explains per-mode PDF behavior, auth, and cost, leaving nothing an agent needs in order 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?

There is a single parameter, and the schema documents it at 100% coverage ('The id of a study you ran'), matching the description's own phrasing. The description adds nothing beyond the schema, 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 states a concrete verb-and-resource pair: it returns a study's page URL and PDF availability, and it explicitly says it returns a link, not the file. That is specific enough to act on. It never distinguishes itself from the sibling get_simulation, so an agent cannot tell from this text alone which one to call to inspect a 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?

Usage context is clear: it is free, it applies to a study you ran, and you must be signed in as the account that ran the study. It also states which study types (Pulse, compare_options, screen_creatives) produce a PDF, and which (Ads Labo, pricing, MaxDiff) do not. It names no alternative tool and gives no exclusion rule, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden and does: it discloses the cost/duplication hazard of re-running, the async lifecycle (study keeps running after a timeout or recoverable error), the recommended polling cadence, and the status state machine. It also warns which error shapes are recoverable.

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 core purpose, then the failure-recovery path, then the return shape. Dense but every sentence carries operational information; no filler or restatement of the name.

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

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

No output schema exists, yet the description compensates by describing the return shape ('same shape as the run tool that started it, plus a top-level status' with enumerated values). For a single-parameter read tool this leaves nothing an agent needs unstated.

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

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

Schema coverage is already 100%, so the baseline would be 3, but the description adds real meaning by explaining that sim_id can come either from a run tool's success response or from the sim_id field of a recoverable error — context the schema only states tersely.

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

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

Opens with a specific verb+resource+key ('Fetch the results of a study you ran, by id') and immediately scopes it as a retrieval-only operation, which cleanly separates it from the run_* siblings that launch studies. An agent can tell what it returns without opening the schema.

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

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

Gives explicit when-to-use cases (read a study again, recover a run whose tool call failed), an explicit prohibition with the reason ('Do NOT re-run the tool — that launches and charges a second study'), and a concrete recovery procedure (wait 30-60s, call get_simulation(sim_id), poll while status is 'running'). Nothing is left 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?

With no annotations, the description carries the burden and does disclose the return shape and a subtle semantic detail (panel_age_range is often wider than age_range). It is implicitly a safe, stateless enumeration, but never states there are no side effects or how large the list may be.

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

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

Front-loaded with purpose, then usage routing, then return shape. Every sentence — including the panel_age_range clarification — earns its place and prevents a downstream mistake.

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?

No output schema exists, yet the description enumerates the returned fields (key, label, description, age_range, panel_age_range) and their meanings, so an agent knows exactly what it gets and how to use the key.

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 tool takes zero parameters, so the baseline of 4 applies; there are no parameter semantics to clarify beyond the empty 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 ('List all available demographic presets') and immediately defines what a preset is (a calibrated mix of demographics + Big Five OCEAN distributions). This distinguishes it from simulation siblings like run_focus_group, which consume rather than enumerate presets.

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

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

Explicitly says 'Call this first if you don't know which preset to use', which is exactly the discovery condition, and names the two downstream consumers (run_focus_group / run_debate) plus the field to pass (demographic_preset). The routing is fully 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?

With no annotations, the description carries the full burden and does: it discloses cost ('Free'), ordering ('newest first'), pagination behavior ('next_offset is set when there may be more'), and scoping ('the studies you ran'). These are exactly the traits an agent needs before calling a list endpoint repeatedly.

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 ordering, then routing, then return shape. The one inefficiency is restating the field list twice — loosely in prose ('the question, mode, status, date, market...') and again as the returned object's keys.

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?

No output schema exists, so the description supplies the full return shape including every key and the pagination fields. Combined with cost and ordering disclosure, an agent has everything needed to call and consume the result.

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 meaning is already documented. The description still adds the pagination contract — that next_offset signals more pages — which is output semantics not conveyed by the input 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 concrete verb and resource ('List the studies you ran') plus scope ('newest first') and content ('the summary the web app's dashboard shows'). It is clearly separable from get_simulation, which fetches a single study by id.

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

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

Explicitly routes the agent: 'Use it to find a sim_id for get_simulation, ask_followup, share_study, get_report_link, validate_study or record_outcome.' That names both the use case and the six downstream alternatives, leaving nothing 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?

With no annotations present, the description carries the full burden and does so: it declares the call is free ('no wallet debit, no rate-limit penalty beyond the regular per-key limit'), explains the charging model ('a completed vote is charged exactly this', 'respondents who fail to answer are never charged'), and flags a failure mode ('within_agent_cap (false means ... the real call would 400)'). It also notes brief_warnings 'never block a run', which is a behavioral fact an agent could otherwise misread as a gate.

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 correctly (what it does, then cost/free status, then the return fields) and split with clear headers, so an agent can stop reading early. It is on the long side: the brief-check section enumerates eight warning codes with parenthetical guidance, and the custom_audience guidance edge could be trimmed without losing callable information.

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

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

For a 10-parameter tool with a nested object and no output schema, the description fully documents the return shape (estimate_credits, min/max_credits, estimate_cents, min/max_cents, expected_seconds_min/max, plan, agent_cap, within_agent_cap, plus brief_warnings) and explains the settle-range semantics. Nothing an agent needs to invoke or interpret it correctly appears to be 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 earns more by explaining how parameters interact rather than restating them — e.g. comparison_tier must be paired with mode='comparison' and num_options, its panel sizes (35/150/400), and 'leave population_size out'. It likewise explains what to pass for the brief check (topic, options, demographic_preset, custom_audience) and enumerates the resulting warning codes, which is meaning the schema cannot convey.

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 two specific outputs ('estimate the cost (credits) and runtime (seconds)') and names exactly which sibling tools it prices (run_focus_group, run_debate, compare_options, screen_creatives, test_ads). The phrase 'WITHOUT actually running it' cleanly separates it from those 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?

Gives an explicit trigger ('use this when you need to budget before committing') plus a hard rule for autonomous agents ('preview before any sim with population_size > 100 or any debate at all'). It also routes a related need to a different tool: 'Preview a custom_audience with the free estimate_reach tool before paying for a run'.

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

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

With no annotations, the description carries the burden and does most of it: it discloses cost ('Free'), overwrite semantics on re-record, a 16 KB payload cap, and the return shape { ok, simulation_id }. It still omits permission/auth requirements and whether the replaced record is recoverable.

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 action and purpose, then constraints, then return value; roughly four tight sentences with little waste. The 'so CrowdOS can keep calibrating' clause and the 'Free.' fragment are mild padding but serve selection decisions.

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 5-parameter mutation tool with a nested object and no output schema, the description covers the critical gaps: the at-least-one-input rule, overwrite behavior, payload limit, cost, and a lightweight return contract. The 'notes' field is left to the schema and no error behavior is described, so it is not fully exhaustive.

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 would be 3, but the description adds real value beyond the schema: the at-least-one-of constraint across accuracy_rating/ground_truth/ground_truth_data is not encoded in the schema, and it supplies a concrete example and size limit for the nested ground_truth_data object.

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

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

States a specific verb and resource: record real-world outcomes for a study you previously ran, with the downstream purpose (calibration) named. It is clearly distinct from siblings like get_simulation or list_simulations, though it never explicitly contrasts with a near-neighbor.

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

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

Gives a clear trigger ('after a study you ran') plus a hard input constraint ('Pass at least one of: ...') and an upsert rule ('Recording again replaces the earlier record'). No explicit when-not-to-use or named alternative, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses the billing model (wallet charged per respondent), the cost formula population_size × num_rounds, plan caps, and that individual answers are deliberately excluded from the return. It also warns that more rounds means more convergence pressure, which is genuinely behavioral. It loses a point for an internal inconsistency: it claims "the default debate is 30 respondents × 5 rounds" while the schema caps population_size at 20 and defaults it to 20, so an agent relaying the default to a user would misstate 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?

Front-loaded with purpose, then clearly delimited blocks (RECOMMENDED FLOW, plan limits, WHEN IT FITS / WHEN IT MISLEADS, Returns). The Returns enumeration and the flow block both earn their place, but the cost point is made three times (wallet rate, population_size × num_rounds, "so preview it"), which is more repetition than a complex tool needs.

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

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

For a 9-parameter, nested-object, no-output-schema, paid, non-annotated tool, the description covers everything an agent needs: what it costs, how to check cost first, plan caps, when to use a sibling instead, and a full enumeration of returned fields including num_rounds, position_shifts_count and the breakdown dimensions. Nothing material is missing apart from the default disagreement noted above.

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 properties already document topic, context, language, num_rounds, custom_audience and population_size, so the baseline is 3. The description adds useful cost-per-round reasoning and a concrete pre-check (estimate_reach for custom_audience), but it also contradicts the schema on the population default (30 vs 20), which actively undermines parameter understanding rather than adding to 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?

Opens with a specific verb+resource ("Run a multi-round simulated debate") and immediately describes the mechanism: respondents discuss over rounds and update positions in response to each other. It explicitly distinguishes itself from the nearest sibling by naming run_focus_group as the tool for the unprompted split, so an agent can route without opening either schema.

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

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

Provides an explicit RECOMMENDED FLOW sequencing list_demographic_presets, preview_cost and user confirmation before running, plus a WHEN IT FITS / WHEN IT MISLEADS pair that names the failure mode (reading results as a population estimate) and the alternative (run_focus_group). Alternatives and exclusions are both 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?

No annotations are provided, so the description carries the full burden and does: it discloses blocking duration (5–120s scaled by population_size), billing to the account wallet at web per-respondent rates, plan caps with a retry rule on error_type=over_plan_cap, and the privacy constraint that only aggregate sentiment is returned, never individual answers. Small-group suppression (min_group_size) and the panel_check caveat are also surfaced.

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

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

Front-loads the one-line purpose, then uses caps-labeled blocks (RECOMMENDED FLOW, WHEN IT FITS, WHEN IT MISLEADS, Returns) so an agent can skim to the needed section. It is long and repeats the plan-cap figure already in the population_size schema, which keeps it from a 5.

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

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

With no output schema, the description fully specifies the return payload — id, status, sentiment_summary with counts and shares, counted_agent_count, breakdowns by age/gender/ideology/region/party with min_group_size suppression, total_responses, billing. For an 8-parameter, nested-object, paid, blocking tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds real meaning on top, notably that stance_statement changes how positive/negative are interpreted (sentiment_axis = Agree/Disagree) and that image_url costs ~1–3s regardless of population_size. It largely restates the custom_audience preview advice already in the schema, so it stops short of a 5.

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

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

Opens with a specific verb+resource ("Run a simulated focus group (a Pulse vote)") and scopes the accepted inputs (question, policy, product idea, stance). The WHEN IT FITS / WHEN IT MISLEADS block explicitly separates it from compare_options, and later sentences route image/video/ad work to screen_creatives and test_ads, so an agent can distinguish it from every relevant 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?

Provides an explicit RECOMMENDED FLOW naming list_demographic_presets and preview_cost in order, plus the free estimate_reach preview for custom_audience. It also states a negative condition — option-picking questions belong to compare_options, not this tool — which is exactly the when-not guidance the dimension rewards.

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

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

With no annotations, the description carries the full burden and does so well: it discloses wallet charging, per-respondent pricing, runtime and timeout behavior, media validation before charging, plan-based creative limits, and that results exclude individual answers. These are exactly the behavioral facts an agent needs before invoking a paid, long-running study.

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 long but appropriately sized for a complex paid study tool, and the core purpose and creative-input rules are front-loaded. Every paragraph earns its place by covering flow, pricing, validation, tiers, timeout handling, and return fields.

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?

There is no output schema, but the description lists the returned fields and explains the key result shapes for solo and ranked modes. Combined with the detailed input schema and operational guidance, an agent has enough information to call the tool correctly.

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

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

Although schema coverage is already 100%, the description adds substantial meaning beyond the schema: it explains acceptable media formats and sizes, the requirement for direct public file links rather than web pages, plan-specific creative limits, tier respondent counts, and how to price a run. It also clarifies the relationship between comparison_tier, media count, and preview_cost.

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 screens videos or images in Screening Room and clearly distinguishes solo review from ranked comparison. It also names the outputs, making the tool’s purpose unmistakable relative to its siblings.

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

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

It gives a strong recommended flow: if the audience is unset, use list_demographic_presets, price with preview_cost, confirm with the user, then run. It also explains timeout recovery via get_simulation, but it does not explicitly say when not to use this tool or which sibling to use instead for other kinds of evaluation.

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

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

With no annotations, the description carries the full burden and does so well: it discloses what the shared page reveals (question, sentiment split, panel size, three quotes), what it never reveals (full results, cost, who ran it), that it is free, that it is idempotent ('Asking again returns the same link'), and that it is revocable via the web app.

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

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

Front-loads the core purpose in the first clause and keeps every sentence informative, including the return shape in lieu of an output schema. Slightly dense but no wasted 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?

No output schema exists, so the description supplies the return shape ({ sim_id, share_url }) plus the privacy/idempotency/revocability semantics. 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 description coverage is 100% with a single required param, so the schema already documents sim_id. The description's phrase 'a completed study you ran' reinforces the constraint but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Get the public share link for a completed study') and immediately distinguishes it from the web app's general report by describing what the page contains vs. what it withholds. An agent can tell this apart from siblings like get_report_link and get_simulation.

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

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

Explicitly scopes usage: 'Share only when the user wants the study public' and notes the link can be turned off from the study's page. It also constrains input to 'a completed study you ran.' It does not name a competing sibling by name, but the when-to-use condition 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?

With no annotations, the description carries the full burden and does: it discloses wallet billing at per-respondent rates, the ~15 minute wait with progress reporting, the timeout/retry hazard, and the aggregation level ('You get the totals, without individual answers'). It also pre-empts misinterpretation by framing predicted rates as a panel's reading benchmarked against placement and industry, 'not a forecast of a live campaign'.

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

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

Purpose is front-loaded and the paragraph order (what it does → pricing → input rules → flow → returns) is logical. There is some duplication: 'Every plan tests up to 4 creatives on a panel of 100, 200 (the default), 400 or 1,000, the sizes the web offers' restates the population_size enum and media maxItems, and the long Returns block is dense, but it is load-bearing given there is no output schema.

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

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

For a 7-parameter tool with nested objects, no annotations and no output schema, this is unusually complete: it documents the return shape per mode, billing, latency, timeout recovery, input validation rules, and how to interpret the numbers. An agent has everything needed to call it correctly and handle the failure case without guessing.

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 earns above that by adding constraints the schema does not carry — accepted file types and the 10 MB image / 100 MB video caps, and the requirement that the link open without signing in and point at the file, 'not a page that shows it'. It also ties population_size and media count to pricing, which the schema does not.

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

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

Opens with a specific verb+resource ('Test ad creatives in Ads Labo') and immediately explains the mechanism: a simulated panel scrolls past the ad in a chosen placement. It clearly splits the two modes (1 creative = predicted metrics, 2-4 = comparative verdict), so an agent knows exactly what it gets. It stops short of naming which sibling to use instead (e.g. screen_creatives or compare_options), so sibling differentiation is only 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?

The RECOMMENDED FLOW block gives an explicit ordered sequence with named siblings: list_demographic_presets when no audience is picked, preview_cost for pricing, confirm with the user, then run. It also states the error path precisely ('On error=timeout with a sim_id... collect it with get_simulation, do not re-run'), which prevents duplicate spend. What's missing is any exclusion rule against the other analysis siblings.

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

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

With no annotations, the description carries the full burden and discloses key behavior: the check is free, it saves the check with the study, and it refuses studies without a sentiment split. It does not cover permissions, re-run/overwrite behavior, or failure modes beyond refusal, but the main traits are clearly stated.

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 and appropriately sized: purpose and restrictions come first, parameter clarification follows, and the return shape comes last. Because there is no output schema, the explicit return summary earns its space.

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

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

Given the nested real_distribution parameter, no output schema, and the need to understand study-type restrictions, the description is complete enough to call the tool correctly. It explains accepted input forms, refusal cases, persistence behavior, and the full returned metric shape.

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 useful meaning beyond the schema: real_distribution may be percentages summing to 100 or raw respondent counts, and maps positive/neutral/negative to agree/undecided/disagree when the study had a stance_statement.

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: check a completed study against real data and return how far the simulated split was from it. It also distinguishes compatible studies (sentiment split from run_focus_group) from incompatible ones (debate or ranking).

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 when the tool works and when it does not: only for a study with a sentiment split, while a debate or ranking is refused. It also names run_focus_group as the relevant sibling for the supported study type.

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