sync_my_ads

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

The description explicitly says 'Read-only — never writes to Meta', which is a strong behavioral guarantee. Since no annotations are provided, this is crucial. It also mentions that it queues the sync and that ads land a few minutes later, setting expectations about asynchronous behavior. It lacks some details like rate limits or failure modes, but given simple scope, it's good.

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 concise, only 3 sentences. It front-loads the action ('Queue a read-only sync'), then gives usage context, then timing and safety. Every sentence adds value, no fluff.

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 there are no parameters, no output schema, and no annotations, the description does a good job covering the key facts: asynchronous execution, read-only guarantee, and where results appear. It could mention what happens if Meta is not connected (likely an error), but the 'when to use' condition covers that implicitly. Otherwise, it's complete for a simple action.

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?

There are zero parameters, and the schema coverage is 100% (vacuously). The description explains that it syncs the user's own ads, an implicit parameter (the user identity) that is not in the schema. It doesn't need to describe parameters because there are none. Baseline for 0 params is 4, and the description appropriately mentions the scope (user's own).

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 is very specific: it queues a read-only sync of the user's own Meta ads and insights, exactly matching the tool name 'sync_my_ads'. It also distinguishes itself from sibling tools by explicitly targeting the user's own ads, not competitors' ads (e.g., search_competitor_ads, get_my_competitor_ads).

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 clearly states when to use: when the user's ad library looks empty or stale and Meta is connected. It also implies when not to use (if Meta is not connected) and differentiates from sibling tools that focus on competitors. It points to a related tool (list_my_ads) for seeing results, providing useful navigation.

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