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

Annotations only say it is not read-only, is open-world and not destructive; the description adds the details that matter: work happens asynchronously in the background, results are persisted to the person's Puley history, and an email is sent. Those are real side effects an agent must warn about before invoking. The re-call behaviour is disclosed too, though it sits slightly oddly against idempotentHint=false (a repeat call returning the existing run reads as deduplicated).

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 sentences, front-loaded with the background/one-shot nature, then the parameter hint, then the polling rule. Every clause carries information. Minor awkwardness in the run-on phrasing of the first sentence slightly hurts scanability.

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 steps up by naming what the report contains and how the result reaches the user (history plus email). Combined with the polling note and the parameter hint, an agent has enough to invoke it correctly. Only the delivery timing and failure behaviour remain unspecified.

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 single parameter has zero schema description coverage, so the description must carry the meaning — and it does, stating that 'competitor' accepts either a name or a website. That is exactly the disambiguation an agent needs to pass a valid value. It could go further on domain/format expectations, but the core gap is filled.

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 gives a concrete verb chain and a concrete artifact: it reads a competitor's live ads and website, then writes what they push, how they sell and the gaps to use. That is far more specific than the name 'competitor_report' alone. It does not name the neighbouring tools an agent might confuse it with (company_brief, account_report, find_ads, read_site), so sibling differentiation is only implicit.

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 frames the operating context — 'Runs once, in the background' — and tells the agent how to follow up: repeating the same request yields progress or the finished report. That is genuinely actionable polling guidance. It stops short of explicit exclusions or named alternatives for when a lighter tool would be better.

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