mailchimp_audiences

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

With no annotations, the description carries the full burden. It describes data returned for each action, which is helpful, but does not explicitly state the tool is read-only, discuss rate limits, pagination caveats, or error conditions. The disclosed behaviors are limited to output summaries, not the full operational profile.

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

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

The description is lengthy but each clause earns its place by defining one of the 12 actions. The structure is logical: first the umbrella scope, then a list of actions with inline descriptions, ending with parameter dependencies. It is not unnecessarily verbose, though it could be slightly tighter.

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

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

Given the tool's complexity (12 actions, 6 parameters, no output schema), the description is remarkably complete. It summarizes what each action returns and flags which IDs are required. It lacks explicit error/edge-case behaviors, but for a data retrieval dispatch tool, the coverage is strong.

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

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

The action parameter's enum is explained in detail within the description, going well beyond the schema's terse 'See the tool description.' The description also clarifies the role of list_id and webhook_id/merge_field_id in context. Other parameters are already well-described in the schema, so the added value is above 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?

The description names a specific resource (audiences/lists) and clearly enumerates all sub-resources and actions, distinguishing it from sibling Mailchimp tools. It uses a specific verb pattern ('Get', 'retrieve' implied) and explains the purpose of each action, making its scope unmistakable.

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 explicitly says to start with the 'list' action to get a list_id, guiding the agent on the correct first step. It also clarifies which action needs webhook_id and merge_field_id. It does not explicitly mention when to use an alternative sibling tool, but given distinct resources, this is acceptable.

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