get_audience_details

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

Annotations already declare readOnlyHint=true, but the description adds useful behavioral info: 'Returns 404 error if list_id is invalid.' No contradictions. Could mention idempotency, but not required for a read operation.

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?

Well-structured with sections: purpose, usage, error, args, returns. Concise yet comprehensive. A few extra lines about return fields could be trimmed but overall 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?

Given output schema exists, the description provides ample context: purpose, usage, error handling, parameter details for one param, and return structure. Lacks coverage for 'account' parameter, but otherwise complete.

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 0%, so description must compensate. It fully explains list_id (format, example, source) but completely omits the optional 'account' parameter. Documentation is partial, missing meaning for one of two parameters.

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?

Description clearly states 'Retrieve full stats, subscribe URL, and rating for a specific audience.' It identifies a specific verb ('retrieve') and resource ('specific audience'), and explicitly distinguishes from sibling 'list_audiences' which browses all audiences.

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

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

Explicit usage guidance: 'Use when you have a list_id and need detailed metrics... Use list_audiences to browse all audiences and discover list_ids instead.' It also provides a prerequisite (list_id from list_audiences).

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