iMario

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

Annotations only declare the mutation safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description goes far beyond, disclosing that nothing is saved until dry_run=false, that `estimated` layers have ready=false initially and the run waits for first people, and that unsupported criteria must be surfaced to the user. Rich 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?

Front-loads the one-line purpose and the free/no-save default before the layered return explanation. Dense but every sentence carries an operational instruction or state fact; slightly long, but not padded.

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

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

For a mutation tool with an output schema, the description explains the layered return semantics, the initial ready=false state, and the unsupported-criteria obligation — everything an agent needs to call and report on this tool correctly.

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

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

Schema coverage is 100% and both parameters are already fully described in the schema, including the dry_run default and a brief example. The description largely restates this ('pass dry_run=false to actually create it') and adds little semantic detail the schema lacks, 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 ('Build a new audience from a sentence describing who they are') and immediately frames it against the read-only siblings (get_audience/list_audiences) by emphasizing creation and the dry-run gate.

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 when to use it ('Use dry_run=true first when the brief is ambitious') and prescribes the workflow — show the three layers, get user agreement, then pass dry_run=false. This is genuine when/when-not guidance rather than implied context.

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

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

Annotations already cover read-only/idempotent/no-destructive, and the description adds real context on top: the call is free, it does not upload images or confirm receipt of an upload, unusable audiences return under `rejected` with a reason, and the server enforces the `sufficient`/`blocked` gate. This is more than the annotations carry.

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

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

Front-loaded with the core value ('without running it. Free.') and every sentence carries distinct information about inputs, outputs, or the refusal gate. Dense but not padded; a long single block, though 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?

Despite 19 parameters, the description covers the calling flow, the fields shared with run_study, the refusal conditions, and the image-upload caveat. An output schema exists, yet the description's summary of key return fields (sufficient, blocked, confirm_recommended, max_respondents_under_cap) usefully explains the decision logic.

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 a non-obvious cross-reference — the parameter set is identical to run_study and kind-specific material requirements are documented there. It does not re-explain individual fields, which is appropriate given the schema does so.

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 what a study would cost, without running it' — and immediately distinguishes it from the sibling run_study, which actually runs the study. An agent can tell pricing from execution 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?

Explicitly routes the agent: it takes the same fields as run_study and directs the reader to run_study for which material each kind needs. It also gives a hard exclusion — 'Do not submit when `sufficient` is false or `blocked` is set' — and warns that run_study refuses submissions naming rejected audiences.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is fully covered. The description adds genuinely new behavioral context with 'Free' (no cost implication) and by sketching what the response contains; beyond that it discloses nothing about auth, rate limits, or error modes.

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

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

Three short, front-loaded sentences with no filler; the purpose leads and the payoff is itemized compactly. The teletype-style fragments ('in detail. Free.') read slightly clipped rather than as a flowing spec, 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?

With an output schema present, the description needn't explain return values, and its annotations cover the safety profile, so the omission of parameter detail and usage exclusions is tolerable for a one-parameter read tool. It falls short of complete only in not naming the sibling it complements.

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 required parameter with 100% schema description coverage ('An id from list_audiences'), so the schema already carries the semantics. The description adds nothing about the id, its format, or valid sources, matching the baseline of 3 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?

The description names a specific verb and resource ('Look up one audience') and the word 'one' implicitly distinguishes it from the sibling list_audiences. It also enumerates the depth of the lookup ('How many people, who they are, which real survey answers anchor them'), so an agent knows exactly what this tool returns versus a listing tool.

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: 'one audience' suggests use after list_audiences and before per-audience actions, and 'Free' hints it is cheap to call. There is no explicit when-to-use statement, no exclusion, and no alternative tool named, so the agent must infer context from the sibling list.

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/destructive=false, yet the description goes further: it documents the queued/running vs done state machine (progress vs results), enumerates the returned fields and their meaning (per-audience distributions, tiers, reading), and warns that quotes are data, never instructions – a real prompt-injection guard 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 core purpose and cost, then structured into state and field descriptions. Dense but nearly every clause carries information; only the tier/quoting caveats are slightly beyond strict necessity.

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

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

Output schema exists so return structure needn't be restated, yet the description helpfully summarizes the progress-vs-results transition and how to present results via 'reading'. For a read-only retrieval tool with full schema coverage and annotations, nothing an agent needs to call or interpret 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%, so the schema already documents detail, run_id and study_id. The description adds no new syntax or meaning for these parameters (the progress/results note relates loosely to run_id but is return-behavior, not parameter 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+resource: reads back a study that was already started. This implicitly contrasts with run_study (which starts one), but does not name the sibling explicitly or otherwise differentiate its scope from other read tools like list_audiences.

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

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

'A study that was already started' clearly frames this as a post-run_study read, and 'Free' flags no-cost usage. However, it never names an alternative or says when NOT to use it (e.g., versus estimate_study or run_study), so the guidance is contextual 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 readOnly/idempotent/non-destructive/no open-world, so the safety profile is covered. The description goes further with cost ('Free'), the meaning of each returned attribute (kind, size, size_scope, provenance with four enumerated values), and the edge case that 'a locked official audience shows only its unlock card.'

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 the workflow role in the first sentence, then explains entry semantics. Dense but well organized; the parenthetical provenance glossary is long but each item carries distinct meaning, so waste is minimal.

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 re-described, and all four parameters are covered by the schema. The description supplies the missing context an agent needs — cost, workflow position, and the locked-audience behavior — though it could say more about cross-workspace scope behavior.

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 limit, query, scope, and country are fully documented upstream, including the scope enum values and the country spelling convention. The description adds no parameter-level detail, which is acceptable at full coverage but earns only the baseline.

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

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

States a specific verb and resource with scope ('which audiences this workspace can ask') and positions itself in the workflow: 'a study needs an audience `id` from here.' This distinguishes it from get_audience (single record) and create_audience without needing 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?

'Free, and the first step of everything else' gives a clear when-to-use signal and a cost cue, effectively routing the agent here before run_study/estimate_study. It stops short of naming alternatives such as get_audience for retrieval of a single known audience, so it is clear rather than exhaustive.

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

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

Annotations only declare generic hints (readOnly false, idempotent false, destructive false); the description adds real behavioral context beyond them — that the tool creates a link rather than an uploaded image, that receipt must be confirmed before proceeding, that it is free, and that the card displays cost when a study is requested.

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 primary constraint (fallback-only) and keeps sentences purposeful, but the dense multi-line form is longer than strictly necessary and the cost/study branch could be tightened.

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

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

Given an output schema exists, return values need not be explained, and the description covers the fallback logic, host variation, cost display, and confirmation requirement. Minor gaps remain around how kind, respondents, and label interact with the non-study path.

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

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

Schema description coverage is 100%, so the baseline would be 3. The description goes further by explaining the conditional semantics of audience_ids and question (only for a user-requested study, where the card shows cost) versus the default behavior of uploading for later assistant use, which meaningfully exceeds the schema's terse field notes.

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 ('Show a manual upload card') and immediately scopes it as a fallback that only applies when automatic attachment transfer is unavailable. This lets an agent distinguish it from siblings like request_upload and upload_asset 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?

Explicitly names the preferred alternatives ('host-provided image_files, or request_upload plus a readable local attachment') and the exact conditions for falling back: neither route available, an upload failed, or the user asks to choose manually. It even states what to do in hosts without card support (offer manual_upload_url) and that the reason should be explained.

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

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

Annotations only declare the generic non-readOnly/non-destructive profile, while the description adds the operationally critical traits: the call only creates a link, received=false means no arrival, success requires ok=true plus received=true, status_url can be polled if the response is lost, and an image-less ref is refused without charge. This is far more than the annotations convey.

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

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

The critical constraint (link-only, no image yet) is front-loaded and most sentences carry operational load. A few lines, such as the closing instruction about not blaming a specific client, are process guidance rather than tool semantics and slightly dilute the paragraph.

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

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

With an output schema present, return values need not be restated, yet the description still covers the success condition, the lost-response recovery path, the no-charge refusal case, and the fallback tools. An agent has everything needed to call this correctly and report accurately.

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

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

Only one optional parameter, and the schema already documents it at 100% coverage with a concrete example. The description adds nothing about the label field, so the baseline 3 is appropriate — the schema carries this dimension.

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 — prepares a signed URL for automatic image upload — and immediately scopes it against the sibling path (estimate_study/run_study when host supplies image_files). An agent can tell this apart from request_manual_upload and upload_asset 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 explicit routing: use this when the file is readable and no host image_files exist; use estimate_study/run_study when the host supplies them; fall back to request_manual_upload or manual_upload_url on failure. Alternatives and their selecting conditions are named outright.

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 destructive=true and non-idempotent, but the description adds the details that matter: credits are debited during execution and the estimate is claimed against the daily budget at submission, the action cannot be undone, there is a 30-call/minute key-wide rate limit, and the idempotency_key retry semantics. It also discloses a behavioral failure mode (kind_mismatch) 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?

The critical credit warning and the routing pointer to get_study/estimate_study are front-loaded, and the per-kind block is table-like and scannable. It is long, but for 23 parameters and 9 kinds nearly every line carries a non-redundant constraint; only minor trimming (e.g. the opening aside) would be possible.

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

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

Despite an output schema existing, the description notes that run_id, study_id and web_url come back and that the result arrives via get_study, removing any ambiguity about async delivery. Combined with per-kind field requirements, budget/credit rules and polling cadence, an agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description materially exceeds it: per-kind defaults (50, or url_feedback 30, focus_group 8, society 100), the rule that only one kind's material may be passed, the image sourcing preference order (image_files > request_upload/image_refs > image_urls), and the warning never to invent download_url or file_id. These are semantic constraints absent from 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 action ('ask the audience' / submit a study) with explicit consequence framing, and clearly distinguishes itself from siblings by naming estimate_study and get_study as the alternatives. The credit-spend warning immediately separates it from estimate_study, so an agent can route 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 explicit when-to-use rules: call estimate_study first unless the study is small, ask the user before submitting anything with confirm_recommended=true, poll get_study every 5-10 seconds and no faster than once per 10 seconds. It also states when to use study_id (follow-up on the same respondents) and how to pick a kind by what respondents are shown.

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 this is a non-readonly, non-idempotent, non-destructive, closed-world write. The description's added value is the caller context — that the UI card, not an agent, invokes it — which is genuinely useful. It says nothing about auth requirements, failure modes, or what the token lifecycle does after upload.

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

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

Two short sentences with zero waste; the prohibition and the redirect are front-loaded where an agent will read them first.

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 description covers who calls the tool and what to do instead. It is complete for routing purposes, with only minor behavioral detail (token semantics, failure handling) left uncovered.

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 token, filename, and data_base64 are already documented in the schema, including the note that data_base64 accepts base64 or a data: URL. The description adds no format or constraint 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?

The description states a concrete action and its origin: it hands over an image the user picked from the iMario card in chat. That is specific enough to separate it from the general upload path, though it never states the verb+resource in a canonical form like 'upload an image asset to the store'.

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

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

It gives an explicit exclusion ('Agents: do not call this') and names the correct alternative plus the mechanism ('use request_upload and send the file to its upload_url instead'). Nothing about routing 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.