DesPromesses

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds that results are published declarations ordered alphabetically, which is useful, but says nothing about return shape, empty/missing declarations, or the 2-5 limit being enforced.

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 single front-loaded sentence with no filler; the parenthetical ordering note is the only extra, and it carries real information about result sequencing.

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 two fully documented parameters, no output schema, and annotations covering safety, the description supplies enough to call the tool correctly and know roughly what comes back (published declarations side by side). Only return-detail specifics are missing, which is acceptable here.

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 100%, so both `theme` and `candidats` are already documented with examples. The description restates the 2-5 range and alphabetical ordering, which the schema already encodes via minItems/maxItems, so it adds little beyond the structured data.

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 on a specific resource: published declarations of 2-5 candidates on one theme, presented side by side. This is clearly distinguishable from fiche_declaration (single record) and rechercher_declarations (search), though no sibling is named explicitly.

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 comparison intent and the 2-5 candidate constraint imply when the tool applies, but there is no explicit guidance on when to prefer it over rechercher_declarations or fiche_declaration. The schema points to lister_themes for theme names, but the description itself offers no routing.

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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine value by disclosing what the payload contains (citation, contexte, date, source, archived copy, formulation history), which is the main behavioral unknown for a detail-read tool.

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 single front-loaded sentence, no filler, and the enumerations of returned content earn their place by telling the agent what to expect. Nothing is repeated from the schema or annotations.

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 one required parameter, full schema coverage, and annotations covering the safety profile, the description supplies the remaining missing piece by effectively summarizing the return content in the absence of an output schema. Only the error case (unknown id) is left unaddressed.

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 100% and the schema itself clarifies that the id is the same 'id' field used by the other tools, so the parameter is fully documented. The description adds nothing further about the identifier, which is acceptable given the schema baseline.

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 names the specific resource (a single declaration's detail sheet) and enumerates the content returned: exact quote, context, date, source, archived copy, and formulation history. That clearly separates it from list/search siblings like lister_candidats or rechercher_declarations, though no sibling is named explicitly.

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?

Usage is only implied by the singular 'd'une déclaration' and the id parameter: fetch one record by identifier. There is no explicit statement of when to prefer this over rechercher_declarations or comparer, nor any prerequisite context.

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 cover safety (readOnly, idempotent, non-destructive, closed world). The description adds useful behavior beyond that: results are sorted alphabetically and each entry includes identifiant, parti, statut de candidature, and nombre de déclarations publiées. It does not mention pagination or empty-result behavior, but with zero parameters the risk is low.

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 single compact sentence, front-loaded with scope and ordering, followed by the returned fields. Every element 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?

With no parameters, no output schema, and annotations covering safety, the description completes the picture by naming the returned fields and ordering. Nothing an agent needs in order to call it correctly is missing.

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 tool takes zero parameters, so the baseline is 4. There is nothing to clarify in the input schema, and the description does not need to compensate for missing parameter documentation.

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?

States a specific verb and resource: lists all referenced candidates. The alphabetical ordering and field enumeration make its scope clear enough to distinguish it from sibling tools like rechercher_declarations and lister_themes.

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 phrase 'Tous les candidats référencés' implies full enumeration with no filtering, which hints at when to use it. However, it does not explicitly name alternatives such as rechercher_declarations or explain when not to use this tool.

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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that each entry carries an identifier and a count of *published* declarations, which is useful behavioral context about the data returned, but it says nothing about ordering, volume or pagination.

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 single short sentence with no waste, front-loading the resource and the returned attributes. It is a noun phrase rather than a full clause, which is marginal but acceptable for a trivial zero-argument tool.

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 zero-parameter, read-only list tool with no output schema, the description supplies the key missing piece: what each item contains (id + published declaration count). Ordering and expected list size are the only remaining gaps and are minor.

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 tool takes zero parameters, so the baseline is 4. The description correctly implies no filtering input is needed and instead characterizes the output fields.

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 names the specific resource (les thèmes du site) and the two attributes returned (identifiant, nombre de déclarations publiées), which lets an agent distinguish it from siblings like lister_candidats or rechercher_declarations. It does not state an explicit verb, relying on the title 'Lister les thèmes', but the resource is unambiguous.

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?

There is no indication of when to use this tool versus the siblings (comparer, fiche_declaration, lister_candidats, rechercher_declarations), nor any preconditions or exclusions. The agent must infer usage from the resource name alone.

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 declare read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: results are ordered most recent first and paginated at 20 per page. This helps the agent understand result presentation and pagination, though it doesn't cover rate limits or error behavior.

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 tightly written sentences front-load the core purpose and then include essential behavioral details (ordering, pagination, optional filters). No wasted words, and the information is presented in a logical order.

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?

Given the tool's complexity (7 optional filters), the description covers purpose, ordering, and pagination. With no output schema, it could briefly mention the return format (e.g., a list of declaration summaries), but annotations and schema cover most needs. It is largely complete for an agent to invoke correctly.

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 high (86%), so parameter meanings are mostly documented in the schema. The description only adds that all filters are optional, which is already evident from the schema (no required parameters). It does not provide additional semantics beyond the schema, so baseline 3 applies.

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 a search operation on published declarations, with ordering and pagination details. It does not explicitly differentiate from sibling tools like fiche_declaration or comparer, but the verb 'Recherche' and resource 'déclarations' make the core purpose clear.

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 usage by describing the search scope and noting all filters are optional, but it provides no explicit guidance on when to use this tool versus alternatives such as fiche_declaration or comparer. The agent must infer appropriate contexts.

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