Generate a market report

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses meaningful runtime traits: simulated latency (~2s per section), background execution, restart safety, and cooperative cancellation. It does not mention return values or auth, but the core execution model is well communicated.

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 with no filler. The first sentence front-loads the most decision-relevant fact (simulated slow job, per-section cost), and the second sentence lists behavioral capabilities. Every word earns its place.

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 and the description does not state what the call returns (e.g., a job ID) or how to poll or cancel it via the durable_task_* siblings. For an async-job tool, this leaves an incomplete operational picture; an agent would not know how to complete the workflow from invocation through cancellation.

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 50%: 'topic' has a description, while 'sections' does not. The description adds behavioral meaning to 'sections' via '~2s per section,' which helps the agent understand performance implications. However, it does not explain what a section is, how topic shapes the report, or the meaning of the default value, so it only partially compensates for the schema gap.

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 states a specific action ('Simulates a slow job') and a resource ('~2s per section'), with the title supplying the report-generation context. It clearly communicates this is a simulation/demo of an async job, which is distinct from a generic report generator. However, it does not explicitly state 'generates a market report' and leans on the title for that framing.

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 description implies the tool is for demonstrating background execution, progress polling, restart-safe state, and cooperative cancellation, which gives an agent a sense of when to use it. It does not explicitly name alternatives or say when not to use it, nor does it point to the durable_task_* siblings for polling/cancellation. The usage context is present but underdeveloped.

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