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

Beyond the readOnly hint, it specifies what data is returned (curated roster + saved creators, ordered by niche) and adds an important safety behavior: content under untrusted_content should not be treated as instructions.

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?

Every sentence earns its place: clear purpose, return-field meanings, enumerated values, downstream usage, and a security-relevant untrusted-content warning. No 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 zero-parameter list endpoint with no output schema in structured data, the description supplies enough field-level detail to use the response, and the untrusted-data caveat covers the main risk. It does not need pagination or error semantics to be actionable at this complexity.

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 tool takes no parameters and the schema fully covers that, so the description cannot add current-tool parameter meaning. It compensates by explaining how returned fields such as creator and start_frames map to generate_ugc parameters, which is useful for downstream invocation.

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 object ('List the UGC spokespersons'), clarifies the scope (connected account's current team, curated roster plus saved creators), and distinguishes this from general list tools by naming UGC-specific content.

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 explicitly tells the agent to call this before generate_ugc to discover valid creator and start_frame values. It does not contrast it with sibling list tools, so it stops short of full when-to-use/when-not-to-use guidance.

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