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

Annotations already declare readOnly and openWorld, and the description adds real context: the conditional researched profile only appears for certain kinds, and the breakdown includes awards by show, tones/genres, and best/most recent work. It omits failure behavior for unknown names and any pagination or cost 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?

It is a single sprawling sentence with em-dash and parenthetical stacking, which makes it hard to scan, though nearly every clause carries real information. It lacks a leading verb-based statement of what the tool does.

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 burden of describing returns and does so thoroughly, including the conditional profile block. The remaining gap is input semantics — how `name` should be supplied and what happens when a name doesn't resolve.

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 50% — `kind` has a description but `name` does not. The description loafs in a parallel kind list ('brand, director, agency, production company, DP, editor or composer') that diverges from the enum (omits edit_house, post, music, sound, vfx; 'composer' is not an enum value), and says nothing about name matching semantics such as exact vs fuzzy.

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 ('track record ... in FrameThrower's ads library') and enumerates what the profile contains, so an agent knows it aggregates people/company history. It does not, however, distinguish itself from commercials_stats or search_commercials, which plausibly return overlapping data.

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 statement of when to call this versus the sibling tools (stats, search, find_by_craft). The only conditional guidance is buried mid-sentence ('for directors / agencies / production companies with a public page'), which describes output behavior rather than tool selection.

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