PickFu

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

Annotations already flag this as a destructive, idempotent, non-read-only operation, but the description adds the details that matter: the call has a real monetary cost that only occurs on confirmed execution, it is a two-phase preview/consent flow, and idempotency is achieved by reusing operationId after uncertain responses. The execution-gate notes (personal unavailable, team rollout gate) are behavioral context found nowhere in the structured fields.

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

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

The purpose and the required preview-then-execute flow are front-loaded, and nearly every sentence carries operational weight. There is mild duplication of the schema's respondentsAmount and previewToken wording, but no filler sentences.

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

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

For a destructive, spend-incurring, idempotency-sensitive mutation, the description covers the cost gate, the consent token flow, the idempotent retry pattern, and the eligibility constraints. An output schema exists, so return-value explanation is correctly omitted, and nothing an agent needs to invoke this safely is missing.

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

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

Schema description coverage is 100%, and the key clarification that respondentsAmount is a new TOTAL rather than an increment is already documented in the schema property. The description restates that plus the allowed-package-size rejection behavior, so it mainly reinforces rather than adds new parameter meaning; baseline 3 applies when the schema carries the load.

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?

"Adds more respondents to a completed PickFu survey" gives a specific verb (adds), resource (respondents), and target scope (completed, panel-sourced surveys), which separates it cleanly from siblings like duplicate_survey, publish_survey, or stop_survey. The agent knows exactly what domain action this performs without opening the schema.

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

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

The description spells out the operating procedure: preview is the default and spends nothing, confirm the preview, then send preview:false with previewToken and operationId to execute, and reuse the identical command after an uncertain delivery. It also names exclusions (personal execution unavailable, team execution gated, survey must be panel-sourced and completed), leaving little to inference.

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

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

Annotations already declare readOnly/idempotent/no-destructive, and the description is consistent with them by framing the output as a URL that acts only when opened. Beyond that it discloses non-obvious behavior: previews are heavy and off by default, external hosts can be rejected requiring upload_media re-hosting, and duplicate-question waste is priced per question.

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 action, then workflow guidance, then structural warnings and an example — each sentence carries information. It is on the long side and the mockup/generate_image advice is repeated in the schema, but nothing is filler.

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

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

For a 6-parameter tool with nested questions/options, an output schema, and rich annotations, the description covers the prerequisites (generate_image, upload_media), the pre-launch preview workflow, and the structural pitfalls an agent would otherwise get wrong. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully reinforces cross-field constraints ('FLAT array', 'exactly ONE content type', 'do not double-nest') and supplies a concrete example payload mapping questions/targeting to the schema. It stops short of explaining country/reporting/sampleSize semantics beyond what the schema already states.

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

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

States a specific verb+resource ('Generates a URL that creates a new PickFu survey') and clarifies the deferred semantics ('when opened'), which cleanly separates it from siblings like publish_survey and generate_image. An agent can tell immediately what this returns and what it does not do.

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 to generate_image 'first' for hypothetical mockups, tells it when to set previewImages: true and to show those previews to the user before launching, and even flags the pitfall of two options sharing an image. This is when/when-not guidance plus named alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds the pending/complete state model and the 'in selection order' detail, which is meaningful context beyond the annotations.

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

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

Three sentences, front-loaded with purpose and scoping, with no filler. The inline return-shape JSON is slightly redundant given an output schema exists, keeping it just below top marks.

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, rich annotations, and full parameter coverage, the description only needs to add workflow context — and it does, explaining the upload-then-check sequence and the media-cdn.pickfu.com URLs to continue with.

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

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

Schema coverage is 100% and the single token parameter is fully documented in the schema. The description's '(no args)' refers to upload_media, not this tool, and adds no syntax or format detail beyond the schema's token description. 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 ('Check the status of a PickFu-hosted upload session') and immediately ties it to the sibling that creates it (upload_media). An agent can distinguish it from upload_media without opening either schema.

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

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

Gives an explicit trigger ('Call this after the user returns from the upload link') and names the origin tool (upload_media), so the workflow position is clear. It lacks an explicit when-not statement, but the sequencing guidance is strong.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false, so the mutation/idempotency profile is covered structurally. The description adds useful organizational context (tags are scoped to your organization/account), but omits what happens on a duplicate name and whether the tag can later be removed.

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

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

Two tight sentences, purpose front-loaded, no filler or restatement of the title. Every sentence earns its place by adding either the operation or the scope.

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 tool is simple with one fully-documented parameter. The only real gap is behavior on duplicate names and any permission requirements, which the description leaves unaddressed.

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

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

Schema description coverage is 100% and the single 'name' parameter is fully documented in the schema including length and uniqueness constraints. The description's scoping note ('organization/account') adds marginal meaning to the uniqueness rule but nothing the schema doesn't already imply.

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

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

States a specific verb and resource ('Creates a new tag') plus the domain (PickFu surveys) and scoping model. It is easily distinguished from the sibling list_tags, though it never names that sibling explicitly to reinforce the create-vs-list 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?

There is no when-to-use or when-not-to-use guidance, no mention of prerequisites such as needing an existing survey or project, and no pointer to list_tags for checking whether a tag already exists. The agent must infer all routing from the verb alone.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is carried by structured data. The description does add genuine value by disclosing that drafts are soft-deleted while published surveys are archived with data preserved, but it restates idempotency and says nothing about permission requirements or error behavior for missing/foreign surveys.

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 with zero filler; the core action is front-loaded and the outcome differentiation follows immediately. Idempotency is the only mildly redundant clause given annotation coverage.

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

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

An output schema exists, so return values need not be explained, and the draft-versus-published outcomes are the key behavioral fact an agent needs before invoking a destructive tool. Minor gaps are permissions and behavior when the survey does not exist or is not owned by the caller.

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

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

Schema description coverage is 100%, including enum documentation for idNamespace, so the schema carries parameter semantics entirely. The description adds no additional meaning about surveyId format or when to supply idNamespace, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Deletes or archives a PickFu survey') and immediately clarifies the two outcomes, so an agent knows exactly what the operation does. It does not explicitly contrast itself with siblings like stop_survey or publish_survey, which keeps it just short of a 5.

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

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

Usage is implied by the verb and the draft/published distinction, giving the agent context on when the destructive path applies. There is no explicit guidance on when to use this versus stop_survey or publish_survey, nor any stated prerequisite (e.g., ownership or permissions).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds substantially beyond that: the response shape (ranked matches with scores, reasoning, pricing, plus recommended audiences), the existence of a low_confidence signal, the English-only limitation on trait labels across all countries, and the note that time_expectation is null in this version. Those are exactly the behavioral traits an agent needs to interpret results correctly.

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

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

Core purpose and the sibling alternative are front-loaded, and the fallback conditions follow in a compact list. The final sentence about time_expectation is slightly abrupt and the sentence covering response contents plus save_survey.targeting chaining is dense, but no sentence is filler.

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

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

For a 3-parameter discovery tool, the description covers input intent, failure modes, output composition, and the downstream handoff ('pass chosen permalink values to save_survey.targeting'). Even though an output schema exists, the description's explanation of low_confidence and recommended audiences adds the interpretive context needed to act on results.

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 67%; query and countryCode are documented in the schema, while limit only has type/default/range bounds. The description compensates partly by framing query as a free-text audience description and by disclosing that trait labels are English-only, which constrains what language the query should be written in. It does not explain the limit parameter or ranking cutoff behavior, so it adds meaningful but not complete semantic value.

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

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

The description opens with a specific verb and resource: 'Finds ranked audience targeting matches from a country and free-text description.' It explicitly positions itself against the sibling list_available_targeting, so an agent can distinguish browsing the catalog from querying it without inspecting 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 states the primary use case ('when the user describes an audience in words') and three concrete fallback conditions for switching to list_available_targeting: wrong-looking matches, a low_confidence flag in the response, or a non-English query. This is explicit when-to-use and when-to-switch guidance rather than implied usage.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true; the description goes beyond them by spelling out the consequence of non-idempotency, the draft being unpaid, Mini allowance restrictions carrying over, and a concrete recovery path. It does not clarify whether the source survey is ever affected or what permissions are required, which would matter for a destructive-flagged 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?

Front-loaded with the core action and result, then escalating to edge cases in roughly priority order; sentences are dense but each carries information. It is near the upper limit of length for a single-operation tool but avoids filler.

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

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

An output schema exists, so the description need not document return shape, and the preservation/failure notes cover the main behavioral questions for a duplication tool. Residual gap is the unexplained sampleSize and externalId parameters, which an agent cannot infer from anywhere.

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 43%, and the description adds meaning mainly for tagIds/projectIds via "Overrides replace the copied associations." The other parameters — sampleSize, externalId, name — are neither described in the schema nor explained here, so the coverage gap is only partly compensated.

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 ("Duplicate an owned survey") plus the exact output object ("a new unpaid draft"), which cleanly separates it from save_survey, create-style siblings, and get_survey. The preservation list further pins down what the copy contains.

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

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

Gives clear routing for the failure case ("repair the returned draftId with save_survey") and an explicit anti-retry rule ("repeating duplication creates another draft"). It also scopes usage implicitly to owned surveys, but never states what to do for non-owned/template sources or points to get_template/list_templates as the alternative.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the bar is lower, yet the description still adds substantive context: scope and permission requirements, the short-lived signed token embedded in CSV URLs so clients can follow links without their own auth header, and the fact that results arrive as resource_link content blocks. These are exactly the operational details an agent cannot get from the annotations.

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

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

Four sentences, each carrying distinct information, with the core purpose front-loaded and the operational caveat (signed token) placed after the usage instructions. No filler or repetition of the tool 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?

With an output schema present, return values need only light treatment, and the description still usefully characterizes them as downloadable resource_link blocks. Auth, permissions, filtering, and link-following behavior are all covered; the omission of `csvVersion` and `idNamespace` semantics is the remaining shortfall for a 5-parameter tool with three enums.

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 80%, so the baseline is 3, and the description mostly restates what the schema already says about `format` (limiting returned formats) and `language` (ISO 639-1 filtering of PDF/PNG entries). It adds nothing about `csvVersion` or the genuinely ambiguous `idNamespace` collision-disambiguation parameter, both of which would have benefited from explanation.

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

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

The description uses a specific verb and resource: 'Returns download URLs for a completed survey's results in CSV, PDF, and PNG formats.' That is far more precise than the name alone and is clearly distinct in kind from data-returning siblings like get_survey_responses. It stops short of naming the sibling it replaces, so an agent must infer that this tool yields links rather than response payloads.

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

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

It states the prerequisites for use clearly (authentication, `read` scope, caller must be able to view the survey) and explains how to narrow output via `format` and `language`. It offers no explicit when-not or 'use X instead' guidance relative to get_survey_responses or generate_report, which is the only real gap.

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

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

Annotations already declare the safe/read-only/idempotent profile, but the description adds critical operational constraints not present anywhere else: HTTPS-only, size cap (5 MB), accepted formats (JPEG/PNG/GIF/WebP, no SVG), and an explicit host allowlist.

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 action, then constraints, then the alternative workflow. Every sentence earns its place, though the closing local-file workflow sentence is somewhat dense and 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?

An output schema exists, so return values need not be explained. Given a single-param, read-only tool, the description covers purpose, constraints, and the fallback path completely.

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 urls parameter is already documented (type, 1-20 bounds, format). The description expands the allowlist far beyond the schema's abbreviated version (cloudinary, cloudfront, s3, Amazon subdomains), adding genuine meaning, though item-level count is already in the schema.

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

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

States a specific verb (fetch and return) and resource (images from URLs) plus the agent-facing purpose (view and describe them). It is immediately distinguishable from siblings like generate_image and upload_media, which are named where relevant.

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 states when to use it (URLs from the allowed host allowlist) and when not (local image files), routing the agent through the exact alternative workflow: upload_media (no args) -> present link -> check_upload. 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?

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial context beyond them: preparation does not spend, generation requires confirming with the returned operationId, reuse the same operationId after uncertain responses, and the async requestId path returns imageGeneration with status and terminal result. The logo-fidelity limitation and 'pending is not a completed image' guidance are exactly the kind of behavioral disclosure an agent needs. Minor gap: it never explains why destructiveHint=true applies.

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

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

The purpose and the mockup-first instruction are front-loaded, which is good, but the middle is a dense run-on chain covering two execution modes, cross-tool upload steps, and status polling. Every topic is relevant, yet the operationId/requestId block could be split or tightened so an agent can parse the two paths at a glance.

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 five parameters, dual sync/async modes, and an output schema, the description covers the full lifecycle: preparation, confirmation, idempotent retry, async continuation, and the post-generation handoff to save_survey/build_poll_url. An output schema exists, so return values need not be enumerated, and the one async return shape it does mention is warranted by the unusual continuation 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% and the schema descriptions already spell out operationId (omit to prepare without spending), requestId (runtime-supplied, correlation only), and referenceImageUrls (max 3, HTTPS allowed hosts). The description largely restates these rather than adding new 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?

Opens with a specific verb+resource ('Generate an image for PickFu research') and immediately splits the two supported intents: new hypothetical/custom product mockup vs. creative variants of an existing asset. This clearly distinguishes it from siblings like extract_images, upload_media, and list_mockup_templates.

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 sequencing rules: call first for a mockup with no existing image, then pass only a completed image_url to save_survey or build_poll_url. It also routes local files through upload_media (no args) then check_upload, and names get_image_generation_status as the alternative for one-shot async inspection.

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 the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false) but the description supplies the operational behavior those hints cannot: cost ('a long model run'), async lifecycle (returns id/url/status immediately, PENDING filling in over minutes), dedupe behavior (returns an existing PENDING/READY report rather than starting another), privacy ('private to the user until they share it'), and a retry policy ('Never retry automatically; after a timeout, check Reports'). Note the dedupe sentence is in mild tension with idempotentHint=false, but it reads as a same-report short-circuit rather than a claim of idempotency, so it is not a contradiction.

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

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

Front-loaded with the purpose, then preconditions, then lifecycle, then the two imperative rules, which is the right order for an agent. It is long but nearly every sentence carries an operational constraint (consent, async status, no auto-retry, refused-when-collecting). The only waste is the partial restatement of the template/ID mapping already fully covered in the schema.

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

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

An output schema exists, yet the description still usefully explains the status semantics (PENDING vs READY, filling in at url over minutes) that a schema shape alone would not convey. Combined with the consent requirement, refusal condition, privacy note, and retry guidance, an agent has everything needed to call this destructive, long-running tool correctly.

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

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

Schema description coverage is 100% and each parameter already documents its role, the srv_ pattern, and the omit-when-using-the-other rule, so baseline is 3. The description restates the template-to-ID pairing ('use template poll-summary with surveyId ... or project-summary with projectId') and adds that project-summary covers 'every poll in a project,' but adds no format or syntax detail beyond the schema.

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

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

States a specific verb and resource ('Generate a PickFu report from a server template') and pins the output to a familiar referent: 'the same report the app's Generate report button makes.' It immediately distinguishes the two operating modes (poll-summary/surveyId vs project-summary/projectId), so an agent can tell it apart from siblings like export_survey_results or list_available_reporting 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 preconditions for use ('once a survey has finished collecting, or once every poll in a project has finished'), a required consent step ('ask the user before calling, because it starts a long model run'), and states the negative case ('A survey that is still collecting ... is refused'). It also names the concrete alternative path when the user already has the report, leaving nothing to inference about when to call.

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 read-only, idempotent, non-destructive, closed-world behavior, so the description is not required to carry safety. It still adds genuinely useful non-schema context: the editor/write authorization requirement and the state-dependent return ("pending" with no URL versus "ready" with the link). The return detail overlaps somewhat with the existing output schema, keeping it off 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?

Three short sentences, each carrying distinct information, with the core purpose and the results-URL disambiguation both front-loaded. No filler or restatement of the title.

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 read tool with a full annotation set and an output schema, the description covers authorization, state semantics, and the main sibling confusion. The remaining gap is identifier guidance for surveyId, which is left entirely to a thin schema entry.

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?

Neither parameter is addressed in the description. The schema documents idNamespace thoroughly, but surveyId has only a type and minLength, and coverage sits at 50%, so the description should have explained what identifier is expected and when a namespace is needed. The mention of "own-audience survey" only indirectly constrains surveyId.

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 ("Get the respondent collection link"), scopes it to own-audience surveys, and explicitly distinguishes the output from the results URL. An agent can tell this apart from sibling retrieval tools like get_survey or build_poll_url 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 clear context for use — you need the shareable link for respondents on an own-audience survey, and you need editor/write access. It also rules out the nearby confusion with the results URL. It stops short of naming a sibling alternative or saying what to do for non-own-audience surveys.

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 behavior, so the safety profile is covered. The description adds genuinely non-obvious domain behavior: refunded=true means the follow-up was never delivered (respondent declined or request expired) and credit was returned, which prevents an agent from misreading empty answers as real data.

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

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

Three sentences, front-loaded with the primary purpose, then the correlation key, then the filtering hint, then the refund caveat. No redundancy or 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?

With full schema coverage and an output schema handling return structure, the description only needs to convey purpose, correlation semantics, and the refunded caveat, all of which it does. Nothing required for correct invocation 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 page, limit, cursor, surveyId, responseId and idNamespace are already documented. The description's note about responseId correlating to the source answer largely restates the schema's own wording, so it adds little beyond 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 ('Retrieves the answers respondents provided to follow-up questions sent on a PickFu survey') and immediately distinguishes itself from the sibling get_survey_responses by explaining that items tie back via responseId. An agent can tell what this 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 clear context for use: it is the follow-up companion to get_survey_responses, and 'Use responseId to filter to follow-ups for a single original response' tells the agent how to narrow scope. It stops short of explicit when-not-to-use guidance or naming alternatives for the unfiltered case.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral facts: the inspection happens exactly once, pending work continues automatically server-side, and "Unavailable is not failed" disambiguates a status value. It also states an output-handling rule (only use completed URLs, render as a clickable link), which annotations cannot convey.

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

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

It is front-loaded with the core purpose and mode split before the rules, and every sentence carries an instruction. It is dense to the point of being a checklist, which slightly hurts scannability but not correctness.

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

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

An output schema exists, so return values need not be described; the description instead covers the status vocabulary (queued/running/succeeded/failed/unavailable), pagination, and the agent's turn-ending behavior. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning on top: runId refers to an already-existing run (not a new one), and cursor should be the nextCursor from the prior page with a 20-per-page cap. limit is left to the schema, which is acceptable given full coverage.

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

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

The first sentence gives a specific verb and resource ("Inspect an existing image generation") and explicitly negates the sibling action ("without starting another image"), which cleanly separates it from generate_image. It also splits the two modes of operation, inspecting one run vs listing handles, so an agent knows exactly what surface it is calling.

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 fully routed: "Supply runId" for a specific run, "Omit runId" to list conversation results, plus explicit exclusions "Do not poll or regenerate." It even prescribes the agent behavior in first-party chat (acknowledge pending images, finish the turn, don't ask the user to check back).

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context the annotations cannot convey: what the returned markdown contains and that its embedded survey-creation links are for the user to open, not for the agent to consume as arguments.

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 no filler, front-loaded on the return value, with the caveat tucked into a parenthetical where it reads naturally. The nested clauses make it slightly dense 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?

This is a one-parameter read tool with an output schema, so the description needn't explain return values or error behavior. It covers purpose, the single input, the shape of the result, and the one non-obvious caveat about the embedded links.

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 the baseline is 3, and the description adds nothing about the slug beyond what the schema already states ("Playbook slug from list_playbooks response"). A note on slug format or how to recover from a bad slug would have pushed this higher.

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

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

The description uses a specific verb and resource ("Returns the full structured playbook for a given slug") and even enumerates the payload shape (goal plus steps_markdown). It is clearly distinguishable from list_playbooks, though it never names get_synthetic_playbook, the closest sibling and a plausible source of confusion.

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

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

There is no explicit statement of when to call this versus list_playbooks or get_synthetic_playbook. The one piece of routing guidance present is negative and useful: the URLs inside steps_markdown are user-facing and must not be fed into save_survey, which steers the agent away from a specific downstream mistake.

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, closed-world and non-destructive behavior, so the safety profile is covered. The description adds modest value by noting that embedded survey data is "lightweight summaries" (pointing an agent to get_survey for full detail), but says nothing about pagination, missing-project behavior, or limits.

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

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

Two tight sentences with the identification mechanism front-loaded and no filler. The enumeration of returned fields slightly overlaps what the output schema already provides, but the wording stays efficient.

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 simple read-by-ID tool with an output schema and safety annotations, the core is covered. The significant gap is the unaddressed pagination surface (limit/cursor) and the absence of any disambiguation guidance against sibling retrieval tools.

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

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

Schema coverage is only 50%: id and idNamespace are documented, while limit and cursor carry no schema description. The description does not mention pagination at all, so it fails to compensate for the undocumented parameters, and "lightweight survey summaries" only hints at the limit/cursor behavior without explaining 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?

"Gets a PickFu project by its unique ID" names a specific verb and resource, and the ID-based lookup implicitly separates it from list_projects. It stops short of explicitly differentiating itself from get_survey or list_projects, so it is clear but not sibling-routing.

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?

"By its unique ID" implies single-item retrieval rather than enumeration, which is enough to infer it is not the listing tool. However, there is no explicit statement about when to prefer this over list_projects or get_survey, and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial behavioral detail beyond them: truncation behavior on large surveys, the responseCount/responsesNote substitution, language fallback returning available languages instead of untranslated content, `results` being null for six specific question types or before any responses exist, averageScore for rating questions, and the optional `pace` object with its nullability caveats. This is exactly the kind of context annotations cannot 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 purpose and type-by-type result behavior, and every sentence carries operative information rather than restating the name. It is dense and long, though; the synthetic-comparison warning and the pace-object paragraph could be tightened without losing signal.

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

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

The tool has a shifting response shape, conditional nulls, and a truncation mode, and the description covers all of these plus the interaction with get_survey_responses. With an output schema present it still supplies enough interpretive context that an agent can call this correctly on the first attempt.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns above that by explaining language semantics in more operational terms (stored translations, fallback behavior when the language is missing). It does not add anything for surveyId, questionId, or idNamespace, and its language-fallback phrasing ('returns the available languages') sits slightly awkwardly against the schema's 'actionable error' wording, keeping it out of 5 territory.

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

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

Opens with a specific verb and resource ('Retrieves a PickFu survey by ID') and enumerates exactly what comes back: metadata, questions, options, AI summaries, responses. It also distinguishes itself from sibling get_survey_responses by explaining that large surveys return per-question results plus a responseCount, so an agent can tell the two apart without opening schemas.

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

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

Gives concrete routing guidance: use get_survey_responses for pagination on surveys with many responses, and only compare against get_synthetic_feedback_results after aligning question/option identities and requiring separate labeling. What is missing is any guidance on when to use this versus list_surveys or export_survey_results, so the coverage of alternatives is partial rather than complete.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds real behavior: omitting page auto-fetches up to 1000 responses within an output budget and a 30-second deadline, cursor continuation is scoped to the same account/limit/filters and starts at the first unseen response, page and cursor must not be combined, and totals are not inferred from a partial result. The language fallback (returns available languages rather than silently untranslated text) is a genuinely useful non-obvious trait. Slight penalty only because the auto-fetch/limit interplay is partly restated rather than fully resolved (e.g., what the caller should do when the 30-second deadline truncates a 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?

Front-loaded with purpose, then usage rules, then per-sibling routing — a sensible order with no filler sentences. The ranked-question passage (1st/2nd/3rd, weighted 3-2-1, instant-runoff round, Vote 1/Vote 2 columns) is long and restates the slowness rationale twice, costing a point on tightness.

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?

Nine parameters, one enum, and a rich pagination model, and the description covers the tricky parts: page vs cursor, auto-fetch bounds, language fallback, and where to go for anything this tool cannot answer. An output schema exists, so omitting return-value detail is appropriate, and nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description still adds meaning the schema does not, namely that omit-page auto-fetch is a single-result mode bounded by output budget and a 30-second deadline, that cursor reuse requires unchanged filters/limit, and the semantic distinction between stored translated explanations and fallback behavior. The ranking/tally guidance is behavioral rather than parameter-level, so it does not lift this further.

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

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

Opens with a specific verb and resource — retrieves PickFu survey responses — and immediately enumerates the payload (explanations, chosen options, respondent demographics), which an agent cannot get from the name alone. It also names the sibling that covers the adjacent job (get_survey for metadata and AI summaries), so the tool is distinguishable 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 routing: get_survey for metadata/summaries, export_survey_results for counts/CSV, list_available_targeting for trait permalinks, rate_response and pin_response for per-response actions. It goes further with a negative rule — do not page through responses to count or score them — and explains why (slow, can outlast the request) plus the correct substitute per case, including the in-progress survey caveat where no CSV exists yet.

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 non-read-only, destructive, open-world call, and the description fills in what that actually means: this only creates a draft, the server picks the audience, NO_MATCHING_PANEL creates nothing, and the request must be user-approved before submission. It also discloses that userInput is analytics-only and never shown to respondents, which no annotation conveys.

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

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

Front-loaded with the core action, then bulleted by mode and by workflow step, which makes a long definition scannable. Some material repeats the schema's property descriptions (imageUrls upload flow, textOptions exclusivity), costing a little density but not clarity.

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

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

For an 8-parameter, multi-mode, non-idempotent tool with no output schema, the description covers the response shape (panel/suggestedPanel, guid, options, sampleSize), the error path, and the mandatory approval gate. An agent has everything needed to invoke it correctly and stop at the right moment.

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

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

Schema description coverage is 100%, so the baseline is 3; the description still adds earned meaning by pairing mode selection with worked examples ('which phrasing is stronger, A: … B: …') and by clarifying that description must carry every variant verbatim and verbatim question text. It largely mirrors the schema rather than extending it, so it stops short of 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: 'Starts a synthetic-feedback research request against synthetic respondents.' It immediately distinguishes itself from submit_synthetic_feedback (only called after approval) and get_synthetic_feedback_results, so an agent can place it in the workflow without opening a schema.

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

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

Explicit branching rules: single vs multi, which argument each mode requires, what to do when the user drops local images (upload_media then check_upload), and when to re-run with list_synthetic_audiences. It also names an anti-pattern ('Never run two synthetic audiences to compare groups') and forbids chaining into submit without an intervening approval.

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?

Although annotations already declare readOnly, idempotent and non-destructive, the description adds substantial behavior the annotations cannot convey: the call blocks up to ~60s (~100s with streaming progress), the return shape depends on research type, `summary_status: "unavailable"` is a possible failure state, and a `next_step` field overrides the resume rule. It also proactively forbids deriving vote shares, counts, mean ranks or margins because twins converge.

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

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

It is front-loaded with the single most important constraint (call once, it stays pending) and organized by outcome case. There is some repetition — the prohibition on vote shares/margins is restated in two places, and the drill-down instruction is described twice — which adds bulk to an already long definition for a two-parameter tool.

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 full burden of explaining returns, and it does so for every branch: comparison summaries (winner/options/sampleReasons/narrative), open-ended summaries, individualAnswers results, and the unavailable state. It also covers the presentation obligations the agent owes the user, which is exactly what is missing from structured fields.

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

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

Schema coverage is 100% and the schema already documents both parameters, so the bar is met by default; the description still adds meaning beyond it by stating that individualAnswers: true returns `results` in place of `summary`, that the two cannot be combined in one call, and that `respondent_id` in an open-ended summary cross-references `segment_name` in results.

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

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

The opening sentence gives a specific verb and resource ("fetches the results of a synthetic feedback request"), which cleanly separates it from the initiating sibling get_synthetic_feedback and from submit_synthetic_feedback. The polling semantics and the guid-based lookup further pin down exactly what kind of result retrieval this is.

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

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

Explicit when-to-call rules are given (call once with the guid; do not call repeatedly; resume only if it returns while IN_PROGRESS), plus a named override for the next_step field. It also routes the agent to a second call mode (individualAnswers: true) with the exact precondition "AFTER presenting the summary", and explains how to relate results to get_survey output without pooling sources.

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/openWorld, so safety is covered; the description adds behavior beyond that, namely the two-mode contract, the shape of list results (id, title, description), and a hard stop-and-confirm gate before executing steps. That workflow guardrail is exactly the kind of agent-facing context 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?

Front-loaded with a definition, then bulleted modes, then a sibling differentiation sentence — easy to parse. It is somewhat long and repeats the mode semantics that the schema field already carries, 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?

Single optional parameter, no output schema needed because the description explains what a list call returns. Nothing an agent needs to call this correctly — including the confirmation gate — is missing.

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

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

Schema description coverage is 100% and the playbookId property already documents 'omit to LIST, pass an id to fetch,' which the description largely restates. The mode framing is useful, but no additional syntax, format, or validation meaning is layered on top of the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Discover and retrieve synthetic-research playbooks') and immediately defines what a playbook is ('self-contained, step-by-step instructions that orchestrate the synthetic-feedback tools'). It explicitly distinguishes itself from the confusingly similar siblings get_playbook/list_playbooks, so an agent can choose correctly without opening either schema.

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

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

Gives explicit two-mode usage: no arguments to LIST, playbookId set to FETCH. It names the alternative tools to avoid and prescribes a post-call protocol (stop, show the user, get explicit confirmation). This is about as complete as when-to-use guidance gets.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the bar is lower, but the description reinforces with domain-specific assurance ('does not publish or spend credits') and enumerates the returned content (constraints, option slots, audience, reporting traits, example link). It does not discuss rate limits or error behavior, keeping it 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?

Front-loaded with purpose and id source, then workflow, then behavior. It is dense but every clause is functional; the enumeration of return fields is somewhat redundant against the existing output schema, costing a point.

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 annotations and an output schema present, the description still supplies the missing pieces: the downstream save_survey invocation pattern, the clickable-link alternative for the url, and the no-credits-spent guarantee. An agent has everything needed to call and use the result 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 there is a single parameter, so the schema carries the load (baseline 3). The description still adds meaning by stating where the id originates (list_templates, cmb_ prefix) and how it feeds into the downstream save_survey call, which is more than the schema provides.

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

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

States a specific verb and resource ('Get one PickFu template') and pins down the identifier source ('by the cmb_ id from list_templates'), which cleanly separates it from the sibling list_templates. An agent can tell exactly what this retrieves 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 routing: fetch by cmb_ id from list_templates, then run it via save_survey with template: { id, blanks, options }. It also names the alternative path ('The url opens it in PickFu's poll builder instead; present it as a clickable link'), so the agent knows both consumption routes.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description adds real behavior beyond that. It discloses result labeling conventions, that dated product updates usually return newest-first (with an instruction to check dates), and a citation requirement to quote policy only from [Help] and cite the URL.

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 action and result labeling, then layered guidance on types and fallbacks. It is dense but nearly every clause carries actionable information; the closing 'Narrow types when the user asks for one kind' partially restates earlier type guidance and is the one soft sentence.

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 search tool with an output schema (which carries nextCursor and result shape) and a fully documented input schema, the description covers what structured fields cannot: intent-to-type mapping, retry behavior, result labeling, and citation rules. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds genuine meaning by mapping specific 'types' enum values to user intents (policy/billing/how-to vs. customer proof), which the schema enum labels do not convey. It says nothing about page, cursor, perPage, or locale, so pagination and localization semantics rely entirely on 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 (searches) and a precise resource set: PickFu help articles plus examples, case studies, and solutions pages. It also names the four result labels, which lets an agent distinguish it from sibling retrieval tools like semantic_search_answers or get_playbook without opening a schema.

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

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

Explicit routing is provided: types ['help'] for policy, pricing, billing, how-to and what's-new questions, and ['case_study','example'] for customer proof. It goes further with a fallback rule (if a mixed search returns no [Help] result, retry with ['help']) and a narrowing rule when the user asks for one kind.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful fact that each trait comes with its permalink, but says nothing about result size, ordering, or what an empty result means.

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?

One sentence, no filler, with the core resource stated first and the optional filter trailing. Nothing is repeated and nothing is wasted.

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

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

For a one-optional-parameter read tool with an output schema and full annotation coverage, the description covers the essentials and correctly leaves return-value structure to the output schema. The only real omission is disambiguation from list_available_targeting.

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 optional parameter with 100% schema coverage, including format examples ('US', 'CA', 'GB') and a 2-character constraint. The description only restates that the filter is optional by country, adding no meaning beyond the schema, which is the baseline for this coverage level.

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

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

The description gives a specific verb+resource ("returns available demographic reporting traits") plus the payload detail of permalinks. It does not, however, distinguish this from the nearby sibling list_available_targeting, which an agent could plausibly confuse with it.

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

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

The phrase "optionally filtered by country" implies the main usage mode and the optionality of the filter, but there is no explicit when-to-use, when-not, or pointer to list_available_targeting as the alternative for targeting traits rather than reporting traits.

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/openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: pagination invariants (same countryCode, query, limit to recover all matches) and the empty-result interpretation caveat. It stops short of describing ordering of returned traits, which is the only 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?

Five dense sentences with no filler, and the scope/purpose is front-loaded ahead of caveats and pagination rules. It is slightly over-packed (semicolon-joined clauses in one sentence), which costs a point on readability, but every sentence carries actionable content.

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 shape, yet it still flags the key fields (total, total_pages, has_more, next_page) and how to advance. All four optional params, the empty-result case, and the sibling handoff are covered — nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema does not: query is explicitly substring-only and 'not semantic discovery', and limit defaults/maximums are restated as operational constraints. The pagination-consistency rule ties page/limit/query/countryCode together in a way the schema never does.

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 ('Browse country-scoped audience targeting traits and exact permalinks') and immediately scopes it against the sibling 'discover_targeting'. An agent can tell this apart from semantic discovery 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 natural-language matching to discover_targeting, tells the agent to omit query to browse the full catalog, to reuse the same countryCode/query/limit when following next_page, and that zero matches means broaden the query rather than that the country lacks targeting. Named alternatives plus when-not conditions are all present.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is partly redundant, but the description adds that it 'does not spend credits' and discloses pagination behavior (default 20, maximum 50, advance page while pagination.hasMore is true) plus a full enumeration of returned fields. It does not describe ordering or filtering of the template list, which is the only real 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?

Purpose is front-loaded in the first clause and the rest is load-bearing (returned fields, pagination, save_survey handoff). It is a dense, comma-chained paragraph mixing return documentation with invocation instructions, and the final 'Read-only; does not publish or spend credits' partly restates annotations, so it is efficient but not maximally scannable.

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 list tool with an output schema, this covers what the schema cannot: the meaning of each returned field, how templates connect to question types, and the exact shape options must take downstream. An agent could construct a valid save_survey payload from this description alone.

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

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

Schema description coverage is 0%, so the description must carry the load; it does so for pagination by stating the default (20), the maximum (50), and the iteration rule 'use page + 1 while pagination.hasMore is true'. That compensates well, though the description never explicitly names the 'limit' parameter, leaving the mapping from prose to the schema field implicit.

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 the mockup templates') and immediately disambiguates by explaining what a mockup template is: a rendering a text option can show instead of plain text, with concrete examples (iOS App Store product page, amazon-search). This clearly separates it from sibling list_templates/get_template and tells an agent exactly what domain object it returns.

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 prescribes the workflow: call this before save_survey, then for each option on a question whose type appears in the template's questionTypes supply { value, mockup: { template: lookupKey, values } }, or the import variant when importSources lists the store. It also scopes amazon-search to click tests only and redirects to save_survey's description for the competitor steps and lookup_listing for competitor data.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds only a field list, which largely duplicates the output schema, and says nothing about ordering, pagination behavior, or result volume. Useful but not additive beyond structured fields.

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

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

Two sentences, front-loaded with the verb and resource, then the drill-down pointer. Every clause carries information; nothing is repeated or 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 simple read-only list tool with full schema coverage, rich annotations, and an output schema, the description supplies everything an agent needs: what is listed, what fields come back, and where to go for detail. No gap remains that the description should fill.

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 page/limit ranges, cursor continuation semantics, and an industry example all documented in the schema itself. The description contributes no parameter meaning beyond that, which is the baseline case when the schema does the heavy lifting.

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

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

States a specific verb and resource ("Lists available PickFu playbooks") and immediately defines what a playbook is ("step-by-step research guides for common use cases"), so an agent unfamiliar with the domain still understands the object. It also explicitly separates itself from the drill-down sibling by naming get_playbook(slug).

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 final sentence gives a clear routing rule: use this tool to browse, then call get_playbook(slug) for the full guide. That is an explicit alternative-with-condition. It does not, however, distinguish itself from get_synthetic_playbook, which appears in the sibling list and could plausibly be confused with this one.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds that results are paginated and filterable, which is modest extra context, but says nothing about result ordering, default page size, or how paging interacts visually with cursor continuation (that detail lives only in the schema).

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

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

Two tightly written sentences with the core purpose front-loaded and supporting capabilities second. Nothing is redundant or padded, though it could be slightly sharper by naming the sibling it is not.

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 5 optional parameters, full schema documentation, an output schema, and read-only annotations, the description covers the essential purpose plus the pagination/filtering model. Only the routing relative to get_project and list_surveys is left implicit, which is a small gap for a simple list tool.

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

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

Schema description coverage is 100%, so the schema already explains page, limit, cursor, archived and bookmarked in detail. The description merely echoes that pagination and archived/bookmarked filtering exist, adding no semantics such as defaults or how unset boolean filters behave.

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

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

States a specific verb and resource ('Lists projects') and clarifies what a project is by saying it organizes PickFu surveys into groups. It does not explicitly distinguish itself from the sibling get_project or list_surveys, so it falls short of full sibling differentiation.

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

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

Usage is implied rather than prescribed: it names pagination and bookmarked/archived filtering as capabilities, which hints at when the tool is useful, but it never says when to use this instead of get_project or list_surveys, nor any prerequisites.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real behavioral context the annotations don't: results are team/account-wide by default and may include other members' surveys, which materially affects the caller's interpretation of results.

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

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

Front-loaded with the core action, then scoping, then return shape; each sentence is legible. The final sentence enumerating returned fields is somewhat listy and partly redundant given an output schema exists.

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 15 optional parameters, full schema coverage, and an output schema, an agent has what it needs to call this correctly. The only soft spot is that the description spends a sentence on return fields the output schema already defines, while not addressing cursor/page interplay.

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?

Definitely not 5 - schema coverage is 100% so baseline is 3; the description restates the `mine` semantics that the schema already documents verbatim, adding no new parameter meaning. It does not cover cursor-vs-page interaction or the comma-separated list formats beyond what the schema 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 and resource ('Lists PickFu surveys') plus the supported capabilities (filtering, sorting, pagination), which clearly separates it from get_survey or the semantic_search tools. It does not explicitly name a sibling alternative, so it falls short of a 5.

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

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

The description explains the default scoping behavior and how to narrow it with `mine: true`, which implies the browse-all-surveys use case. However, it never says when to prefer semantic_search_surveys or get_survey, and gives no exclusions beyond that implicit default.

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, non-destructive, open-world, so the bar is lower; the description still adds the two-mode call semantics (no args returns an index, with `subcategory` returns that subcategory's audiences) and names the returned fields (counts, slug, display name, one-line description). It does not discuss error behavior beyond the NO_MATCHING_PANEL routing or any rate/latency characteristics.

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 the two call modes before the workflow detail, and most sentences carry actionable content. Some length is spent on downstream workflow coaching (present the draft, obtain fresh approval) that belongs to the submit/get tools rather than to this listing tool.

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, and the description compensates by describing exactly what each mode returns (subcategory index with counts and general-audience slug; per-audience name, slug, description). For a zero-required-parameter read tool with full annotation coverage, nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already gives the example and omit-vs-pass explanation, so baseline is 3. The description reinforces the constraint that the value must come from the index and states the different result shape for each mode, adding a bit beyond the structured field.

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

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

The opening sentence states a specific verb and resource (lists synthetic audiences) and immediately scopes it to one subcategory at a time. It also disambiguates vocabulary against PickFu's 'panel' term, which prevents confusion with the sibling targeting/human-respondent tools.

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

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

Explicitly names the alternative (get_synthetic_feedback auto-suggests an audience) and the exact conditions for choosing this tool instead, including specific NO_MATCHING_PANEL reason codes. It also prescribes the post-call flow and an exclusion (never change audience while submitting an existing draft).

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, idempotentHint=true, destructiveHint=false, so the safety profile is covered; the description adds scope ('calling user's' only), ordering, and the default/max limit values. It stops short of describing pagination behavior or what happens beyond the 50-result window, which is the one remaining behavioral 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?

Two tightly packed sentences: the first establishes purpose and return shape, the second routes usage and pins down parameter defaults. No filler, and the identification of what the tool returns is front-loaded.

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

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

With no output schema, the description correctly enumerates the returned fields. Combined with the annotation coverage and full schema descriptions, an agent has everything needed to decide to call it and how to interpret the response.

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 fully documented, including the enum meanings for DRAFT / IN_PROGRESS / COMPLETE. The description restates the status values and the default/max limit but adds no syntax or edge-case detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Lists the calling user's prior synthetic feedback requests'), specifies ordering (newest first) and the exact fields returned (guid, brief description, status, timestamps). This clearly separates it from get_synthetic_feedback and get_synthetic_feedback_results in the sibling list.

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 triggers ('when the user references their earlier briefs / prior feedback or asks what have I run?') and names the downstream alternative it feeds (get_synthetic_feedback_results via guid lookup). The relationship between the two tools is spelled out rather than inferred.

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

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

The annotations already declare this as read-only, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds only modest domain context ('organizing PickFu surveys') and restates search/pagination capabilities already documented in the schema, without additional behavioral details such as rate limits or result ordering.

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 two short sentences, front-loads the core purpose, and contains no wasted wording. Every sentence contributes directly to understanding the tool.

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 simple read-only list tool with a rich output schema, full parameter descriptions, and clear annotations, the description is largely complete. It could be slightly stronger with explicit usage guidance, but it covers the purpose and capabilities sufficiently.

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 all four parameters (page, limit, query, cursor) are fully described in the schema. The description's mention of search filtering and pagination adds no parameter semantics beyond what the schema already provides, so the baseline score of 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: it 'Lists available tags for organizing PickFu surveys.' That clearly distinguishes it from mutation siblings like create_tag, but it does not explicitly name alternatives or contrast with them.

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

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

The phrase 'Supports search filtering and pagination' gives implied usage context, but there is no explicit guidance on when to use this tool versus create_tag or other tag-related operations. It is minimum viable but lacks routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds real context: 'Read-only; does not publish or spend credits', the meaning of pricePerResponse, the note that originalPricePerResponse is only set on some templates, and what the url actually does (opens PickFu's poll builder, not a run action). This is behavior beyond the structured fields, not repetition of them.

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

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

Content is front-loaded with purpose and disambiguation before the pagination and pricing details, and nearly every sentence carries an operational fact. The pricing block (pricePerResponse / originalPricePerResponse) is the densest stretch and partly duplicates what get_template would reveal, making it slightly longer than strictly necessary.

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

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

For a filtered, paginated list tool this covers everything an agent needs: filtering, cursor protocol, default and max page size, the shape of each result, the follow-up chain to save_survey, and how to present the url. An output schema exists, yet the description still names the returned fields and correctly defers originalPricePerResponse to get_template.

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 high (86%) so the baseline would be 3, but the description adds value the schema lacks: it names the four filter concepts, supplies the limit default of 20 and maximum 50 (the schema's limit property carries no description), and explains the cursor contract ('pass nextCursor back as cursor, with the same filters and limit'). It stops short of restating the enum values or the access semantics, which the schema already covers.

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 ('List PickFu templates: ready-made single-question polls, each with a fixed price per respondent') and explicitly excludes the two easily confused siblings: playbooks ('not playbooks, which are multi-poll research plans') and 'not mockup templates'. An agent can distinguish this from list_playbooks and list_mockup_templates without opening any schema.

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

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

Explicit routing is given in both directions: 'Use get_template for one template's full constraints' and 'To run one, call get_template for its blanks and limits, then save_survey with template: { id }'. The pagination condition ('while hasMore is true') supplies a stopping rule rather than leaving it 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?

The description frames the tool purely as a read ('Read a product or app listing', 'It does not create a survey'), while the annotations declare readOnlyHint=false and destructiveHint=true. Nothing in the text explains what could be destructive, whether the lookup consumes credits, or why it is non-idempotent, so the agent is left with a direct conflict between prose and structured hints. The annotation_contradiction flag applies.

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 and the anti-pattern (web page fetch) are front-loaded, followed by source rules and then the downstream mockup-template mapping. The trailing sentences about list_mockup_templates/save_survey are dense but each carries actionable routing information rather than filler, and no sentence merely restates the schema.

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

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

With an output schema present the description needn't document return shape, and it still explains the field-provenance model ('each field carries the provider that filled it; a field the store did not return is absent'). For an open-world, multi-source lookup the only missing pieces are failure behavior (unsupported store, not-found listings) and the cost/side-effect question raised by the annotations.

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 semantics beyond the schema: source must be omitted only when the link's host names the store while a bare id requires it, and a region embedded in the link overrides the explicit region parameter. Only the region default (US) is left purely to the schema, so the added value is genuine if not exhaustive.

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

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

The opening sentence names a specific verb and resource ('Read a product or app listing from its store by id or link') and enumerates the returned fields: title, images, price/currency, rating, ratings count, description, store-specific fields. It also carves out a clear boundary against the obvious alternative ('instead of fetching the web page, which misses details the store renders with JavaScript') and lists the supported sources. An agent can distinguish it from siblings like extract_images or list_mockup_templates without opening any schema.

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

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

Explicit when-to-use ('when the user names a listing and you need what it shows'), an explicit when-not (don't scrape the web page), and an explicit parameter dependency rule (omit source only when the reference is a link whose host identifies the store; a bare id needs source). It even routes downstream: an Amazon result fills one row on the amazon-search mockup template, with the exact field mapping and pointer to save_survey for the steps, plus a negative scope statement ('It does not create a survey').

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

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

Beyond the annotations, the description discloses the external destinations (PickFu's Linear workspace with Sentry as fallback) and that the authenticated user's identity is transmitted, which is meaningful openWorld context an agent would not otherwise know. It also gives a data-hygiene warning about credentials and personal data, though it says nothing about duplicate submissions or failure behavior when neither destination is configured.

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

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

Three tight sentences: purpose first, transmission/privacy second, usage triggers last. No filler or restatement of the title.

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

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

For an 8-parameter reporting tool with full schema coverage and an output schema, the description covers what the agent needs: what it does, where the data goes, what not to include, and when to call it. Return values are handled by the output schema, so no further detail is required.

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 enums for category and severity already documented in detail, so the schema carries parameter meaning. The description adds only the general instruction not to include secrets in the submitted text, which is marginally useful but not parameter-specific guidance.

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

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

States a specific verb and resource ('Submit feedback, suggestions, or bug reports to the PickFu team') and scopes it to the PickFu team, which separates it from sibling tools that write data (save_survey, submit_synthetic_feedback). An agent can identify the operation and its target without opening the schema.

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

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

The final sentence gives concrete triggers: tool errors, confusing behavior, or a user request for improvements. It lacks explicit when-not guidance (e.g., don't use for product support requests, use help_center_search instead), which is a real gap given siblings like help_center_search exist.

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

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

Annotations already declare destructiveHint=true and non-idempotent, and the description adds the specific consequences: publishing burns today's allowance, allowance is shared across teammates on the plan, and eligibility is plan-gated. It also warns that update will reject a surveyId not taken verbatim from create's id field, which is exactly the failure mode an agent would otherwise hit.

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 hard constraints come first, then the create→update→publish sequence with the confirmation gate, then the return shape. Six short sentences, no filler, and the scoping facts are front-loaded where they matter most.

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

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

For a destructive, plan-gated three-action tool this covers what annotations and schema cannot: eligibility, allowance consumption, the mandatory user confirmation before publish, and the id handoff between actions. An output schema exists, so the brief mention of id/status/url is sufficient rather than required.

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 the schema already carries parameter meaning, and much of the description's parameter content (action, surveyId) restates it. The one genuine addition is the cross-parameter contract binding create's response id to surveyId for update/publish; parameters like operationId and idNamespace get no treatment in the 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?

The description names a specific verb set (create/update/publish) against a specific resource (the account's plan-included daily mini-poll), and pins down scope limits — exactly one question, five respondents, no targeting, no reporting, no screen recording. That distinguishes it from siblings like save_survey or publish_survey without the agent having to open 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 gives explicit sequencing (create a draft, read the returned id, pass it as surveyId for update/publish) and a hard precondition: only publish after the user explicitly confirms launch. It also flags plan eligibility and the shared daily allowance. It stops short of naming an alternative tool for full multi-question surveys, so routing away from siblings is implied rather than stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true and openWorldHint=false, so safety is largely covered. The description adds the meaning of a pin and the returned fields, but leaves the destructiveHint unexplained — nothing tells the agent what is 'destroyed' by unpinning or that the operation is safe to retry.

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

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

Three tight sentences with the core action and scope front-loaded and no filler. The closing sentence on return values is slightly redundant given a dedicated output schema exists.

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

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

An output schema exists, so return values need not be explained, and the description covers purpose, scope, and the companion read tool. The main remaining gap is permissions/prerequisites for a mutation flagged as destructive.

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

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

Schema description coverage is 100%, so all four parameters including the idNamespace enum are already documented. The description adds no syntax, formats, or edge cases beyond that, so the baseline of 3 applies.

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

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

States a specific verb pair (pins or unpins) and resource (a response on a completed PickFu survey), plus the scope constraint that the survey must be completed. An agent can tell it apart from rate_response or get_survey_responses 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?

"Use get_survey_responses to see current pin states" names the read-side alternative explicitly, and the completed-survey constraint implies a precondition. However, it never contrasts pinning with the sibling rate_response, nor says when not to pin.

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

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

Beyond the annotations (destructiveHint:true, idempotentHint:false, openWorldHint:true), it discloses non-obvious behavior: a paid receipt does not mean the survey is collecting, quotes can change and require fresh consent, and recharge must never be automatic. The warning that a wrong or duplicated image cannot be fixed once live is exactly the kind of irreversible-consequence context annotations cannot convey.

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

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

Sentences are dense but each carries a distinct operational rule, and the core omit-operationId-to-prepare mechanic is front-loaded. It runs long, and the image-verification detour, while valuable, reads as a appended caveat rather than integrated workflow, keeping 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?

For a destructive, money-spending, open-world mutation, the description covers the confirmation gate, idempotency strategy, failure/refusal handling, and the image-integrity precondition. An output schema exists and annotations cover the safety profile, so nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning about the interaction between operationId and quoteToken — that operationId alone gates whether money is spent and that quoteToken plus operationId is the paying execution. surveyId and idNamespace are left entirely to the schema, which is acceptable given full coverage.

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 ('publish') and immediately reframes it as a two-phase prepare-then-pay operation, which is the crucial distinction from a naive publish. It also implicitly separates itself from siblings like save_survey (used for preview) and stop_survey by defining the whole quote-to-queue lifecycle.

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 branching rules: omit operationId to prepare without spending, repeat with operationId and quoteToken after user confirmation, reuse the same operationId on an uncertain response, and start a new decision for changed quotes or funding refusals. It also names the alternate path for image surveys (save_survey with previewImages:true or extract_images) so the agent knows when not to call publish yet.

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 flag destructiveHint and idempotentHint, but the description goes far beyond them: per-plan flag caps with tier-specific math, error on cap exceedance, cascade rejection of all responses from the same respondent, valid-answer recalculation, possible survey reopening, and the irreversibility of auto-rejection when flipping not_helpful back to helpful. This is exactly the kind of consequence detail an agent needs before a destructive call.

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

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

Front-loaded with purpose, then routing, then a clearly marked IMPORTANT block of consequences; the cap arithmetic examples ('3 flags on a 30-response survey') aid comprehension rather than pad. It is dense but long, and the plan-tier enumeration could be tightened slightly without losing meaning.

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 annotations covering safety, a full output schema, and 100% parameter description coverage, the description supplies the remaining behavioral context (caps, cascades, reversibility) needed for a destructive multi-tier operation. Nothing required 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, but the description adds real semantics for the comment field ('Re-rating without re-sending the comment field preserves the previous comment') and clarifies that 'helpful' simply marks quality while 'not_helpful' triggers auto-rejection. idNamespace is left to the schema, which is acceptable given its own 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 ('Marks an individual respondent comment as helpful or not_helpful') and anchors it to the sibling it follows from, get_survey_responses. An agent can distinguish it from pin_response or semantic_search_answers 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 sequencing ('Use this after get_survey_responses to programmatically curate response quality'), names concrete use cases (flagging low-effort or off-topic responses), and adds a clear when-not/caution rule ('Confirm with the user before applying not_helpful to multiple responses in bulk').

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely useful patch semantics ("Only provided fields are changed"), but it does not disclose the destructive paths the annotations warn about, such as archiving/bookmarking a project or null-clearing goal and description, and says nothing about permissions.

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, no filler, and the create-vs-update fork is front-loaded right after the purpose statement. Every clause carries operative information for the caller.

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

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

An output schema exists, so return values need not be described, and annotations carry the safety profile. However, a 7-parameter tool with zero required parameters leaves open questions the description does not resolve: whether name is needed to create, how idNamespace should be chosen on update, and what happens to unmentioned fields such as archive.

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 id, goal, name, archive, bookmark, description and idNamespace all documented inline, including the null-clears behavior for goal and description. The description reinforces the id semantics but adds no meaning beyond the schema, which is the expected baseline 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 gives a specific verb and resource ("Create or update a PickFu project") and immediately splits the two modes by id presence, so an agent knows exactly which operation it will perform. It does not name or differentiate itself from the closely related sibling save_survey, which is the main thing keeping it from 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?

"Omit id to create; include id to update" is an explicit, actionable rule for choosing between the tool's two modes, and "Only provided fields are changed" clarifies that omitted fields are left alone. It stops short of naming alternatives (save_survey) or stating prerequisites such as which fields are needed for a valid creation.

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=false, and the description elaborates exactly why: 'questions/options without id are created as new, and those missing from the payload are removed', plus repeated calls without surveyId create brand-new drafts. It further discloses constraints annotations cannot express — template is create-only, reporting cannot be sent with a template, amazon-search is refused on non-click_test questions, and rejected drafts save nothing and return every violation.

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?

Nearly every section carries real operational value, but the document is severely mis-front-loaded: it opens with the completionEstimate and cost response fields even though an output schema exists, and the actual purpose statement appears several paragraphs in. It also duplicates schema prose (option content-type rules, mockup import semantics) verbatim, inflating length without adding 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 19-parameter tool spanning 12 question types, templates, mockups, Amazon SERP pages and pricing, the description covers the workflows an agent must chain and the failure modes it must avoid. Return values are covered by the output schema, so the extra cost/completionEstimate explanation is surplus rather than a missing piece.

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?

Well above the 68% schema coverage baseline: it explains that targeting replaces a template's preset audience (so presets must be resent), that omitting likertScale on update preserves the existing scale, that mockup: null removes a question's page while omission preserves it, and which sample sizes (5/10/20/25) force screen_recording questions. A few params — externalId, projectIds, ownAudience, responseSource — get no meaning beyond the schema, which keeps it from 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?

The sentence 'Create or update a PickFu survey. Omit surveyId to create; include surveyId to update.' gives a specific verb, resource and a clear create-vs-update discriminator. It also distinguishes itself from the draft-then-publish flow by telling the agent to hand back the returned id for iteration. It loses a point because that sentence is buried mid-document, so the opening the agent reads first describes response objects rather than the tool's purpose.

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 routing is everywhere: call get_template before using a template, call get_survey before updating questions, use questions at standard pricing when a draft violates template limits, call generate_image before a hypothetical mockup, call extract_images/previewImages before publish_survey, and create one poll per variant rather than a head_to_head. It also states an explicit prohibition (do not add a separate open_ended question for 'why') and the duplicate-draft failure mode of calling without surveyId.

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 readOnly/idempotent/non-destructive/openWorld, yet the description adds substantive behavior: results are grouped by survey and ranked by similarity, each group carries survey_id and url, the url must be surfaced as a clickable link, and the corpus is an embedded snapshot rather than live data. That snapshot caveat is exactly the kind of staleness disclosure 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?

One front-loaded paragraph: what it searches, how results are shaped, the mandatory url-linking instruction, example prompts, then the snapshot caveat. No sentence is redundant with another.

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, and the description compensates by describing the return shape (answers grouped by survey, ranked, with survey_id and url). Combined with the snapshot-vs-live caveat, an agent has everything needed to call it and present 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% and the schema already explains query (semantic, not keyword), keyword (case-insensitive substring), and k (default 30, max 100). The description's restatement of the semantic-vs-keyword distinction and the keyword filter adds marginal value only, 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: semantic search across 'individual respondent answer explanations (the free-text comments)' from past surveys. The 'embedded snapshot' framing plus the pointer to get_survey/get_survey_responses cleanly separates it from the live-response siblings and from semantic_search_surveys.

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?

Concrete example prompts ('what did people say about color', 'concerns about price') and the keyword-narrowing tip make the intended call pattern obvious, and it names the live-data companions. It stops short of an explicit when-not (e.g., 'do not use for structured/quantitative fields'), so 4 rather than 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 carry readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds genuinely non-structured facts: it searches an embedded snapshot of the corpus and does not include full results, results may include AI-generated image descriptions and an ai_summary, and callers must render the returned url as a clickable link. Minor gap: no disclosure of snapshot freshness/recall behavior.

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

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

Front-loaded with purpose, then return shape, then usage rules, then hand-off to get_survey — logical ordering with no filler. It runs long (five-plus sentences, one in caps), and the field-by-field return enumeration and link-rendering instruction could be tightened, but each sentence carries information an agent needs.

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

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

Only two parameters and no output schema, so the description carries the return-value burden — and it does, enumerating survey_id, url, title, question, options, status, plus the conditional targeting, image descriptions, and ai_summary. It also flags the snapshot limitation and the escalation path, leaving no meaningful gap.

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

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

Schema coverage is 100%, with both `query` and `k` documented in the schema itself, so the baseline is 3. The description reinforces the query semantics ('describe the concept, not exact terms') but largely repeats the schema's own wording, and never mentions `k` (default 10, max 50) or guidance on choosing 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?

States a specific verb and resource ('Semantic (meaning-based) search across this account's past PickFu surveys') and immediately scopes it against siblings: not a keyword search, and distinct from list_surveys (structured filtering) and get_survey (full details). An agent can tell exactly what this tool does and does not do 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 trigger prompts ('find my surveys about subscription pricing', 'logo tests we ran'), an explicit exclusion ('This is NOT a keyword search — describe the concept, not exact terms'), and names both alternatives (list_surveys for status/date/type filtering, get_survey for full results). When-to-use, when-not, and next-step routing are all present.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description still adds real value by explaining what destruction means concretely: the survey is marked complete and collection ceases, while nothing is said about existing responses surviving. It does not address permission requirements or whether already-collected responses remain accessible.

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, effect stated first and the irreversibility warning second. No filler or restated name, and nothing could be removed without losing 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 an output schema present, rich annotations, and fully documented parameters, the description only needs to carry the behavioral consequence, which it does. The remaining gap is routing against delete_survey, which matters for a destructive pair but is not addressed.

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

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

Schema description coverage is 100%, and the schema already explains surveyId as a GUID and gives detailed enum semantics for idNamespace. The description adds no parameter-level meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Stops a live PickFu survey', and clarifies the effect ('marked as complete', 'no further responses'). It implicitly separates itself from delete_survey by describing completion rather than removal, but never names that sibling, so an agent comparing the two must infer the 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?

The phrase 'live' survey implies the precondition (a survey currently collecting responses), and 'irreversible' hints at caution before use. There is no explicit when-not guidance or pointer to alternatives such as delete_survey or publish_survey, which are plausible confusions in this sibling set.