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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses three non-obvious behaviors: results are returned chronologically; an empty result does NOT mean no broadcast is planned ('Couverture inconnue' caveat); and local times without UTC offset preserve storage including DST ambiguity. The DST and empty-result notes are exactly the kind of behavioral context annotations cannot convey. No contradiction with annotations.

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?

A dense paragraph where every clause carries information: core semantics first, then pragmatic rules (midnight split, 20:00 example), then storage caveats. It is front-loaded and free of filler. The only minor flaw is that a single unbroken paragraph would benefit from visual separation of the edge-case rules, but no sentence is wasted.

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?

For an 8-parameter tool with no output schema, the description covers date range, time range, timezone conversion, DST ambiguity, midnight-crossing behavior, empty-result semantics, chronological ordering, and sibling-based filtering — far more than expected. The residual gap is the result envelope shape (the schema's page description hints at page_suivante but never describes the result structure). This is minor, but it prevents full self-sufficiency.

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 only 50%, leaving limite, id_film, heure_fin, and heure_debut undocumented in the schema. The description compensates for the most important gaps: it defines date semantics ('deux dates incluses', '31 dates maximum'), time-range semantics (applied daily, minutes included), gives a concrete value example (heure_debut=20:00), and explains the chaines/id_film filters via sibling tools. Only limite remains unaddressed, but the semantically tricky temporal parameters are well covered.

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 opens with a precise verb+object pair — 'Chercher les débuts de diffusions' (search for broadcast starts) — and immediately scopes it: inclusive dates, max 31 days, a daily time range with minutes. This clearly distinguishes it from the siblings: lister_chaines (channel catalog), obtenir_film (single-film metadata), and rechercher_films (movie search). An agent can identify which tool to call without opening the schema.

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 gives concrete operational guidance: filter using IDs from lister_chaines or rechercher_films (explicitly wiring siblings into the workflow), set heure_debut=20:00 for after-8 PM requests, split midnight-crossing ranges into two calls, and respect the 31-date cap. It does not state an explicit 'when not to use this tool' condition that would route to a sibling, so it stops short of 5, but the when and how guidance is strong.

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