Discover and store the ad accounts reachable through a connection

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description discloses two non-obvious behaviors: the write is gated on confirm being true, and there is no server-side dry run, so the confirm preview is the only safety net. That is genuinely useful context an agent cannot infer from the annotation flags; it stops short of saying what happens to previously stored accounts or how repeat runs behave.

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?

Two compact sentences: the operation and endpoint come first, the write-safety caveat second. Nothing is redundant and the most decision-relevant fact (the confirm gate) is front-loaded right after the purpose.

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?

There is no output schema, so the description carries the burden of explaining what comes back, and it only implies the preview via the confirm caveat — the discovered account payload and what 'store' means for existing records are unstated. For a mutation that both reads external state and persists it, this leaves a meaningful gap.

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 67%, below the 80% threshold where the schema alone justifies a baseline of 3. The description reinforces the meaning of 'confirm' and adds the 'no server-side dry run' caveat that the schema lacks, but it says nothing about 'id' (which connection is targeted) or how idempotencyKey interacts with a repeated discovery.

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 pairs a specific verb ('Discover and store') with a specific resource ('ad accounts reachable through a connection') and even names the endpoint, so an agent knows exactly what the call does. It does not explicitly distinguish itself from nearby siblings like adAccounts_list, adAccounts_sync, or connections_health, which keeps it below a 5.

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?

The only usage guidance is the confirmation gate ('WRITE: not executed unless confirm: true'), which tells the agent how to invoke it but not when to choose it over adAccounts_list or adAccounts_sync. There is no statement of prerequisites (e.g., that the connection must already exist and be healthy) or 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.