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

Beyond the readOnly/non-destructive annotations, the description discloses genuinely non-obvious behavior: results are grouped by structure so demo text/colors/images do not create duplicates, filters are applied before grouping, IDs are stable, and pagination is signalled via hasMore. It also warns that templateId always returns a source belonging to that template and that multiple sources can be mixed.

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?

It is dense but front-loaded with the core purpose and free of filler; each clause conveys a distinct rule. The semicolon-chained sentences make it slightly hard to scan, and the language differs from the English tool name and schema keys.

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 search tool with no output schema, the description explains the result shape (variantCount, structureId, stable IDs, hasMore) and the grouping semantics, which is what an agent needs. The undocumented 'category' filter is the main missing piece.

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 only 13% (only 'group' is documented), so the description carries most of the burden and does so for q, kind, elementType, templateId and group with concrete accepted values. 'category', 'page' and 'limit' are only indirectly implied by the hasMore/pagination remark, leaving a residual 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 opening sentence gives a specific verb and resource: searching within the reusable sections and elements of 'Outil' templates. That clearly separates it from generic reads like get_component or list_template_sections, though it never names those siblings as alternatives.

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 provides concrete query examples (aboutme, témoignages, bouton) and rules such as using elementType=shape to reach decorative shapes that are excluded from the general list, plus group=structureId to deliberately surface all variants. However, it never states when to prefer this tool over preview_components, get_component, or list_template_sections, so the routing decision is left implicit.

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