search_fb_ads

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

With no annotations, the description carries the full burden. It discloses the authentication requirement (env var) and the authenticity of data ('ground truth'), which is useful. However, it omits many behavioral details such as output format, pagination, error handling when the token is missing or invalid, and potential rate limits. The description is adequate but not comprehensive for a tool with zero annotation support.

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 a single, tightly written sentence. It front-loads the core action ('Search Facebook Ads Library'), specifies the data returned, and ends with the key constraint (env var). Every word earns its place; there is no redundancy or 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?

Given the tool's relative simplicity (3 params, no output schema) and the presence of several closely related siblings, the description provides a good high-level context. It clearly states what data is returned, which helps distinguish it. However, it lacks guidance on output structure (e.g., is it JSON, array?) and how to handle pagination or errors, which an agent would need for reliable invocation. A 3 reflects that it is sufficient for basic use but has gaps.

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 only 33% (only 'brand_name' has a description). The tool description does not elaborate on the 'limit' or 'country' parameters at all, nor does it explain how they affect the search. Since coverage is low and the description adds no parameter-specific context, it fails to compensate for the schema gaps.

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 specific verb ('Search'), a specific resource ('Facebook Ads Library'), and exactly what data is retrieved ('REAL competitor ad creatives, copy and delivery data'). It also includes a strong qualifier ('ground truth, not VLM guessing') that distinguishes it from sibling tools that might generate or analyze 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?

Implies when to use by emphasizing real data vs. VLM guessing, and mentions the required env var (FB_ACCESS_TOKEN) as a prerequisite. However, it doesn't explicitly name alternative tools from the sibling list or state conditions like 'use this when you need actual ad data, not when you need analysis.' Still, the context is clear enough for an agent to infer appropriate use.

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