Rechercher des produits

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the description carries a lower burden. It adds only generic context (returns list with ID, name, main details) and pagination defaults. It doesn't disclose behavior like field-projection handling of unknown names (though the schema documents that), rate limits, or how keyword matching works (fuzzy, exact). 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?

The description is compact and front-loaded with the core purpose, followed by Args/Returns structured sections. It's ~50 words of meaningful content with no fluff. Mild deduction for the Args section partially restating schema descriptions (page, pageSize defaults already in schema), which is redundant with structured data, though it does co-locate defaults usefully for quick scanning.

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 keyword-search list tool with an output schema, strong annotations (read-only, idempotent, open-world), and a fully-documented schema (100% coverage), the description is reasonably complete. It covers what's searched, pagination, and return shape. Minor gaps: it doesn't mention the fields projection capability in the description (though schema covers it) or clarify that pageSize max is 100 in description vs 500 in schema - a mild inconsistency between default descriptions that could confuse an agent.

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 the parameter burden is largely handled by the schema. Still, the description adds value by clarifying keyword search scope '(nom, email, compétences...)' and explaining pagination semantics. The fields projection parameter (present in schema with 100% coverage) is not explained in the description but the schema covers it. The description's 'détails principaux' hints at return content. Slightly above the baseline-3 because it clarifies keyword semantic scope beyond the schema.

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 'Recherche des produits dans BoondManager par mots-clés avec pagination' - a specific verb (recherche=search) + resource (produits/products) + distinguishing feature (par mots-clés with pagination). This clearly distinguishes it from sibling tools like boond_products_get (single retrieval) and boond_products_create/update/delete (mutations).

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 establishes it's a search-by-keywords tool with pagination, but does not explicitly state when to use it versus alternatives like boond_products_get. It doesn't mention the fields projection parameter's role in choosing between this search and a get, nor contrast with resource/company/candidate searches. The context is reasonably implied (search when you need a list by keyword) but no explicit exclusions or alternatives are named.

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