Askli Customer Research

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

Adds behavior the annotations don't convey: it takes minutes (latency), and results should be presented with Askli's small-sample caveats. Annotations already flag it as non-read-only and non-idempotent, so the description usefully fills in the operational details beyond the safety 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?

Four short sentences, each earning its place: purpose, gating condition, runtime expectation, and result-handling guidance. The core purpose is front-loaded with no waste.

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

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

With no output schema, the description covers runtime ('a few minutes') and how to present results, which is important for an async-feeling analysis trigger. It does not address failure modes (e.g., interviews not yet finished) or whether re-running is safe, leaving minor 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 coverage is 100% for the single studyId parameter, so the schema already documents it fully. The description adds no additional parameter meaning. Baseline 3 applies 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 (analyze) and resource (finished interviews) and contrasts the behavior with the default mechanism (waiting for Askli's next checkpoint). An agent can distinguish this from the study/plan/findings siblings, though no sibling is named directly.

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?

'Only run this if the user asks' gives an explicit gating condition, and 'instead of waiting for Askli's next checkpoint' frames the alternative path. No sibling tool is named as an alternative, but the when/when-not 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 mark this as non-read-only and non-destructive, and the description adds real behavior beyond them: the omit-answer re-fetch behavior, the constraint against answering for the user, and the return outcome (next question or plan ready). Minor gap: it doesn't say what the call mutates or what happens if the answer is invalid.

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

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

Three tight sentences, front-loaded with the core action and followed by constraints and return behavior. Every sentence carries distinct information with no waste.

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

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

With only two parameters and no output schema, the description compensates by explaining the return value ('next question or plan is ready') and the optional-parameter behavior. It covers what an agent needs, though it doesn't detail error or permission 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 coverage is 100%, so baseline is 3, but the description adds semantics the schema lacks: omitting 'answer' is not merely optional, it re-fetches the current question. That clarifies the meaning of the optional parameter beyond the schema's field description.

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

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

States a specific verb and resource: sending the user's answer to a clarifying question. It is clearly distinguishable from siblings like confirm_plan, update_plan, or get_plan, which do not involve answering Askli's questions.

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

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

Gives explicit operating guidance: present each question exactly as asked, never answer on the user's behalf, and omit the answer to re-fetch the current question. It doesn't name alternative siblings or state prerequisites, but the when-to-use context 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 declare a mutating operation (readOnlyHint=false), idempotent, non-destructive, closed-world. The description adds value beyond that: an explicit human-approval gate on user_approved and the assurance that no charge is incurred. It doesn't explain reversibility or what state change participants-chosen entails, so it isn't fully rich.

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 sentences, each carrying weight: purpose/outcome first, then the gating precondition, then the cost note. Nothing is padded or redundant.

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

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

For a two-parameter, non-destructive mutation with no output schema, the description covers purpose, precondition, and cost, which is close to everything an agent needs. Minor gap: it doesn't state what the agent should expect to happen next or whether confirming can be undone.

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 studyId and user_approved are already documented in the schema, which sets the baseline at 3. The description reinforces the approval semantics of user_approved but adds no syntax or format 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?

States a specific verb and resource ("Confirm a reviewed plan") plus the downstream consequence ("so participants can be chosen"), which an agent can use to distinguish this from update_plan or analyze_now. It stops short of naming those siblings explicitly, so the differentiation is inferred rather than stated.

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

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

Gives a hard precondition and when-to-use rule: user_approved may only be set after the user has seen the plan and explicitly approved it. It also preempts a cost concern ("doesn't charge anything"). It does not, however, say when to reach for a sibling like update_plan instead of confirming.

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

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

Annotations cover the write/read profile, and the description adds genuinely non-obvious behavior: it returns a first clarifying question or a 'plan is ready' status, and out-of-scope questions silently create no study. It does not explain idempotency or what happens on repeat calls, so it stays short of a 5.

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

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

Four short sentences, front-loaded with the purpose and trigger, then input handling, then return behavior, then the edge case. No filler and every sentence carries distinct 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?

With no output schema, the description does the work of describing return values (clarifying question vs. plan ready) and the no-op edge case. It leaves the natural next step (answer_clarification / confirm_plan) unstated, which is a minor gap given the sibling set.

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 single parameter's format and length bounds are already documented. The description's 'pass the user's question in their own words; don't rephrase or improve it' adds an emphasis on verbatim fidelity, but largely restates what the schema already says.

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 ('Start customer research with real human participants') and implicitly distinguishes itself from the sibling analyze_now by contrasting human participants with 'synthetic model feedback'. An agent can identify what this tool produces 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 a clear triggering condition ('when a product decision needs evidence rather than synthetic model feedback') and a constraint on input handling, but never names the alternative tool (e.g., analyze_now) or states explicit exclusions beyond out-of-scope questions creating no 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?

Annotations already establish this as a safe, non-destructive, closed-world read, so the bar is lower. The description adds genuine behavioral context beyond that: preserve Askli's counts and caveats, avoid adding conclusions or inflating confidence, and surface insufficiency of evidence plainly. It does not describe pagination, latency, or failure modes.

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

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

Three short sentences, front-loaded with the core action and followed by presentation constraints. Every sentence carries distinct guidance, though the phrasing is slightly conversational rather than maximally terse.

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 read with no output schema, the description adequately characterizes the returned artifact (a Decision Review with counts and caveats) and the handling expectations. Missing only explicit routing guidance relative to the other read 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?

With 100% schema description coverage on the single studyId parameter, the schema already documents its meaning and provenance. The description adds no parameter-level detail, which matches the baseline 3 for high-coverage schemas.

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 ('Read a study's Decision Review'), which is distinct enough from siblings like get_transcript, get_plan, and get_study_status to be identifiable. It does not name or contrast any sibling, so it stops short of the top score.

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 statement of when to invoke this tool versus get_plan, get_study_status, or get_transcript. The one conditional ('If there isn't enough evidence yet, say so plainly') concerns how to present results, not when to call the tool, so usage is only weakly implied.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description's job is to add context beyond that — and it does: it discloses the return shape (structured data plus a text version), the fixed field order, and the non-obvious requirement to present the text verbatim. It omits error behavior for an invalid studyId.

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

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

Two sentences, front-loaded with the purpose, then the return contract. The mid-sentence enumeration of the text fields is long but earns its place by telling the agent exactly what the returned text contains.

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 carries the return-value burden and largely discharges it by enumerating the fixed order of the text version and dictating verbatim presentation. Only failure/empty-plan behavior is left unspecified.

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 studyId parameter is already documented as coming from create_study or list_studies. The description adds no format, sourcing, or constraint detail 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?

States a specific verb and resource: 'Read a study's research plan.' The read-only framing implicitly separates it from confirm_plan and update_plan, though no sibling is named explicitly, so it falls just short of 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?

Usage is implied by 'Read a study's research plan' rather than stated — there is no explicit when-to-use or when-not-to-use guidance relative to get_study_status, get_findings, or confirm_plan. The 'present that text as given' instruction does add a handling directive, which lifts it above a bare 2.

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 a safe, read-only, closed-world operation, so the description's job is to add context beyond that. It does so by framing the call as a payment-verification step and enumerating the state it reflects, though it says nothing about latency, caching, or freshness of the payment status.

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 filler, and it front-loads what the tool returns before the usage trigger. 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?

With no output schema, the description must convey return values, and it enumerates them (stage, interview progress, payment status, next step). Combined with the strong trigger guidance and full schema coverage on the one parameter, an agent has everything needed 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 with 100% schema description coverage, and the schema already explains that studyId comes from create_study or list_studies. The description adds no format, sourcing, or validation detail, 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 the concrete returned artifacts (stage, interview progress, payment status, next step), so an agent knows exactly what a call yields, distinct from siblings like get_plan or get_findings. It never states an explicit verb for the tool itself, relying on the title, which keeps it just short of a top score.

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 precise trigger condition ('when the user returns from the payment page') and asserts exclusivity ('the only way to know whether payment went through'), which tells the agent both when to call it and that no sibling covers this need.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: BYO display-name substitution for authenticated owners, canonical IDs retained, and a hard privacy guarantee that emails and unverified identity claims are never 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 sentences, front-loaded with what is returned, followed by privacy/identity caveats. Every sentence carries information, though the middle identity sentence is slightly dense and could be split for scanability.

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

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

With readOnly annotations, no output schema, and 100% schema coverage, the description supplies what remains: the shape of returned quotes (question plus transcript link) and identity handling. Complete enough to call correctly, though it does not address result volume or pagination.

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 schema already documents all four parameters including formats and examples. The description restates the finding/topic distinction but adds no syntax, precedence (finding vs topic together?) or limit details beyond the schema, so it lands at 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 resource (participant quotes) and its two selection modes (by finding ID/title or by topic), and explicitly ties the finding parameter back to get_findings so the agent can place it in the workflow. An agent can distinguish this from get_findings without opening either schema.

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

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

It tells the agent the two ways to invoke it — a finding from get_findings or a topic — which is clear contextual guidance. It stops short of explicit when-not guidance (e.g. when to prefer get_findings or a broader search instead), so it is not a full 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=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful sort order and field projection, but says nothing about pagination, result limits, or behavior with an empty study list, which matters most for a list 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?

A single sentence with zero filler, front-loading the resource and then the ordering and projection. 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?

With no output schema, the description compensates by naming the returned fields, and the read-only annotations cover safety. The only real gap is pagination/volume behavior, which is minor for a simple no-argument list operation.

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 zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. The description instead usefully documents the shape of each returned item (ID, question, stage).

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 (list) and resource (the user's Askli studies), plus the ordering (newest first) and the projected fields (ID, question, current stage). An agent can tell this apart from get_study_status or get_findings 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?

Usage is only implied: an agent infers this is the entry point for enumerating studies before drilling into get_study_status, get_transcript or get_findings. There is no explicit when-to-use versus get_study_status or get_findings, and no stated exclusions, though the zero-parameter signature limits ambiguity.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the mutation profile is known. The description adds real context beyond that: the precondition that the plan must be unconfirmed, the partial-send semantics, and the post-write behavior that Askli re-checks and may report a different saved result.

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 sentences, front-loaded with the core action and fields; no filler. Minor deduction for the slightly informal phrasing of the closing sentence about Askli re-checking the plan.

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 no output schema, the description covers the key precondition, the field scope, and the return behavior (a re-check with any differences reported). Error and permission cases are not addressed, but the essentials for correct invocation are 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 the baseline is 3. The description goes slightly beyond the schema by naming the four updatable fields and clarifying that only those fields should be sent, which communicates patch-style partial-update behavior the schema alone implies only loosely.

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 ('Change') plus resource ('plan') and enumerates the four mutable fields, while scoping to 'unconfirmed' plans. That scope clause alone distinguishes it from confirm_plan and get_plan 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 two concrete usage rules: only change what the user asked for or agreed to, and send only those fields (partial update). The 'unconfirmed plan' precondition is implied as the when-to-use condition, but no sibling is named as an alternative for confirmed plans.

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