Programme TV Noël

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the read-only nature is established. The description adds valuable context: the limitation about schedule availability and the pagination behavior, going beyond the 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?

Two concise sentences with no fluff. The main purpose is front-loaded, and the limitation and pagination hint follow efficiently.

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 a simple list tool with read-only annotations and two optional parameters, the description covers purpose, limitations, and pagination. It does not describe the return format, but that is not critical for such a tool and no output schema is present.

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%: only 'page' is described in the schema. The description mentions pagination with page_suivante, which helps with 'page', but does not explain 'limite'. The description partially compensates for the coverage gap but leaves 'limite' unexplained.

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 clearly states the action ('Lister' - list), the resource ('chaînes enregistrées' - recorded channels), and the purpose (preparing a filter with examples TF1 and M6). It is distinct from sibling tools that handle films and broadcasts, so an agent can easily tell them apart.

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 provides clear context: it is for listing channels to prepare filters, and it notes a limitation (no guarantee of schedule availability). It also instructs pagination with page_suivante. However, it does not explicitly contrast with sibling tools, though the domain difference is obvious.

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

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

Beyond the annotations, the description discloses meaningful behavior: broadcasts are sorted chronologically from now in Europe/Paris, film:null means absent or masked, and an empty list does not prove absence of future rebroadcasts. These are valuable edge-case semantics not visible in annotations or schema.

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 compact and information-dense with no filler. Each sentence adds a distinct, useful fact: purpose, pagination scope, null meaning, and empty-list caveat.

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?

Despite lacking an output schema, the description covers the essential invocation details: how to obtain the ID, how pagination behaves, ordering, timezone, and edge-case interpretation. An agent has enough context to call this tool correctly and interpret the result.

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?

With schema description coverage at only 33%, the description compensates by explaining that page and limite paginate only the broadcasts, which is crucial for correct usage. The source of id_film is also stated, though limite and id_film lack detailed schema descriptions.

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 verb ('Obtenir'), a precise resource (public film record plus upcoming broadcasts), and ties the identifier to a specific source (rechercher_films). This clearly differentiates it from sibling search/list tools.

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 explains that the ID comes from rechercher_films, which implies when to use this tool after a search. It also clarifies that page and limite affect only the broadcast list, but it does not explicitly state when not to use it or name an alternative for broadcast search.

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

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.

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

Annotations already indicate this is read-only and idempotent, and the description adds substantial behavior: all words must match, constraints of 2–200 characters and max 12 words, no semantic interpretation, and pagination via page_suivante. It also discloses return fields, including absolute URLs, which is useful beyond the 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?

The description is compact and front-loaded: purpose first, matching mechanics second, return shape and pagination third. Every sentence adds distinct value, and there is no filler.

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 a read-only, paginated search tool with no output schema, the description is complete: it names the search fields, defines matching behavior, states the returned fields, excludes casting, and explains how to paginate. An agent has enough information to invoke it correctly with just a recherche parameter.

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?

With only 25% schema description coverage, the description compensates well for the recherche and champ parameters by explaining that all words must appear in chosen fields and how matching works. It also links page to page_suivante pagination. The limite parameter is left to its schema default/name, so coverage is good but not complete.

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 verb and resource: retrieving public films by words in their title or synopsis breakdown. It also clarifies that this is SQL textual search, not semantic, and that casting is not included. It does not explicitly name sibling alternatives, so it falls just short of 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 description gives clear usage context: all given words must appear in the selected fields, search is exact textual SQL rather than semantic, and no casting is returned. It implies when to avoid the tool (semantic needs, cast lookups) but does not explicitly mention sibling tools such as obtenir_film or rechercher_diffusions.

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