list_audiencesLists the authenticated user's Audiences, including member Minds, sharing state, and workspace or shared links. Accepts an optional fuzzy name search.
| Name | Required | Description | Default |
|---|---|---|---|
| searchQuery | No | Search for an Audience by name (fuzzy matching supported) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior. The description adds value by disclosing the composition of returned lists (member Minds, sharing state, links) and the fuzzy-search capability, which are not captured by 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?
Two sentences, no filler; the primary action and the optional parameter are front-loaded. Every clause adds 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?
The tool is simple (one optional param, read-only, no output schema), and the description covers the main output facets and search behavior. It does not mention pagination or empty-result behavior, but these are minor for a straightforward 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% for the single searchQuery parameter, and the description largely restates the schema's fuzzy-name-search semantics. It adds 'optional' but no new meaning 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 clear verb ('Lists') and resource ('the authenticated user's Audiences'), and adds specific content details (member Minds, sharing state, links) that distinguish it from sibling list tools like list_studies. The optional fuzzy search is also noted. This is a specific, non-tautological definition.
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 implies the tool is for browsing the user's audiences and offers an optional search, but it does not explicitly state when to prefer this over alternatives such as ask_audience or export_audience. No exclusions or alternative routing are provided, so an agent must infer usage from the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
The tool set has three distinct get_panel_* tools and two draft-saving tools (plan_panel_study, save_study_draft) that could be confused, but the detailed descriptions clarify their specific scopes. Most other tools (list, create, export, ask) target clearly different resources or actions.
All tool names follow a consistent verb_noun scheme in snake_case (list_, get_, create_, ask_, export_, plan_, run_, save_). Verb choice maps predictably to the operation, making the set easy to navigate.
At 18 tools, the set is slightly above the ideal 3-15 range but well-scoped for a comprehensive research-panel platform. Each tool addresses a distinct part of the workflow, from group/panel creation to study planning, execution, and export.
The surface covers the full research lifecycle: create groups/panels, ask questions, monitor status, export artifacts, and plan/run multi-question studies. It lacks update/delete operations for groups and panels, but these are minor gaps that agents can work around for typical research flows.