TrustyData

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: mode-specific maximum distances (5,000 km car, 500 km vélo, 250 km à pied) with a 422 error response, the fact that duration is only interpretable with the mode, and the OSM ODbL attribution requirement. It also explains that API contract values ('auto', 'pieton', 'velo') are accepted. This goes beyond the annotations without contradicting them.

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 dense but well-organized: it front-loads the core function, then lists outputs, then mode details, then limits, then alternatives. Every sentence adds value. It's slightly long but each piece is necessary for correct invocation (mode limits, plan requirement, attribution). The warning emoji draws attention to the critical constraint.

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 (3 modes, nested origin/destination objects, output schema present), the description covers the essential operational details: mode values, distance limits, error behavior, plan requirement, attribution, and sibling routing. The output schema exists so return values don't need explanation. Minor gap: it doesn't mention whether the route is restricted to France-only or what happens with cross-border routes, but the 'réseau France' is stated upfront.

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 schema already documents all parameters thoroughly (origin/destination with lat/lon/address XOR logic, mode with default). The description adds the mode values ('car', 'walking', 'cycling') and the API contract aliases ('auto', 'pieton', 'velo'), which is useful but the schema already covers the core semantics. Baseline 3 is appropriate since the schema does the heavy lifting.

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 ('Calcule') and resource ('itinéraire complet entre une origine et une destination sur le réseau France (OpenStreetMap)'), and lists the output components (distance, durée, étapes, boîte englobante, géométrie polyline6). It also distinguishes itself from route_matrix by explicitly saying 'Pour de simples distances en masse, préfère route_matrix.' This clearly differentiates it from siblings.

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 explicitly says when to use this tool vs alternatives: 'Pour de simples distances en masse, préfère route_matrix.' It also provides mode-specific guidance (car/walking/cycling), maximum distances per mode, and the plan requirement ('Plan minimum : Business'). This is explicit when/when-not guidance.

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 the description is consistent: 'Récupère' is a read operation. It adds useful context by noting the id provenance and that the details are inline in the other two tools, plus a plan constraint. No contradictions.

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?

Three short sentences; the main action is front-loaded, followed by drill-down context and the plan requirement. No filler or redundant restatement of the schema.

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 a single parameter, a full output schema, and rich annotations, the description covers the essential call context: what it returns, where the id comes from, how it relates to siblings, and a plan constraint. Nothing critical for invoking 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 schema already describes address_id as the id returned by verify_address/search_address, and the description repeats that same provenance without adding new format, constraints, or examples. With 100% schema coverage, the baseline of 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 uses a specific verb ('Récupère'), a resource ('le détail complet d'une adresse'), and a required identifier, immediately distinguishing it from search/verify tools. It explicitly frames itself as a drill-down tool and names the source tools, so an agent can tell it apart from siblings.

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 identifies the relevant siblings (search_address, verify_address) and states that this is a drill-down tool whose details are already inline in those tools, implying when the dedicated call is or isn't needed. It also mentions a minimum plan (Discovery), but does not give an explicit 'use this instead of X when...' rule.

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, idempotentHint, and openWorldHint, and the description consistently aligns with these (no contradiction). The description adds significant behavioral context beyond annotations: the distinction between establishment and legal unit in the response structure, the dependency of detail level on plan, and the crucial warning that absent fields do not imply non-existence. It also explains the 'opposition_prospection' field semantics (true/false/null), which is critical for proper interpretation. This is valuable additional context that goes 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 long and dense, covering many aspects, but every sentence delivers substantive information. The key usage logic (SIRET vs SIREN) is front-loaded, which is good, but the latter half introduces complex plan-level details and field-specific interpretation that could overwhelm an agent reading it for the first time. It is not overly verbose, but it could be better organized to prioritize the most actionable points first.

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 moderate complexity (one parameter, rich response structure with an output schema) and the strong annotations (read-only, open-world, idempotent), the description is quite complete. It explains the response structure, plan-dependent detail levels, the open-world semantics, and the sensitive nature of personal data, which is essential for correct use. It could arguably include a note on rate limits or authorization, but overall it covers the critical context needed for an agent to interpret results 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?

The input schema already fully describes the only parameter (company_id) with its format and meaning, achieving 100% schema coverage. The description reiterates the SIRET/SIREN duality, which adds a bit of context but largely mirrors the schema. According to the rubric, with high schema coverage, a baseline of 3 is appropriate, and the description does not meaningfully augment the parameter semantics further.

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 tool's purpose: retrieving detailed records for French companies or establishments from the SIRENE database. It specifies the exact resource, the two accepted identifier types (SIRET/SIREN), and the corresponding response targets, making its intent unambiguous. It also distinguishes itself from siblings like search_company by focusing on fetching a single record by ID rather than searching.

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 usage context: it explains the two identifier modes (SIRET for establishments, SIREN for the company's head office), which effectively tells the agent when to use each. It doesn't explicitly name alternatives or when not to use this tool, but the clear scope and single-parameter design make the usage context strong. The sibling tools are all search or address-related, so no further exclusion is needed.

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 and idempotentHint=true, so safety is covered. The description adds substantial operational context: network (France OSM), matrix cap (25×25), per-mode distance ceilings, the 422 error case, plan requirement (Growth), and mandatory OSM ODbL attribution. 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 dense but every sentence earns its place: purpose, alternative, modes, limits, and attribution. It front-loads the core function and scopes before constraints. Slightly long but well-organized in a way that supports quick comprehension.

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?

An output schema exists, so return details are handled elsewhere. The description covers everything an agent needs to call correctly: what it does, network, modes, legacy values, limits, error behavior, plan, and attribution. Nothing essential is missing for safe and correct invocation.

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%, so baseline is 3. The description adds value by documenting legacy mode values (`auto`, `pieton`, `velo`) accepted as-is, which the schema does not mention. It also reinforces the XOR lat/lon vs address semantics already present in the schema. This extra semantic detail justifies moving above 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 opens with a specific verb and resource: 'Calcule une matrice de distances et durées entre N origines et M destinations' and immediately scopes it to France/OSM with mode options. It also explicitly contrasts with the sibling compute_route ('Sans géométrie ni consignes'), making the distinction 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?

It clearly tells the agent when to use this tool vs its sibling: 'pour un itinéraire détaillé, utilise compute_route'. It also warns that matrix distance limits (1500 km car, 200 km walk/bike) are lower than compute_route, so a route accepted there may be rejected here with a 422. This gives explicit when/when-not guidance.

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, openWorld, and idempotent hints, so the safety profile is covered. The description adds valuable behavioral details: ranking by relevance, the structure of returned candidates (three postal lines), and enrichment tiers tied to the plan. This goes beyond annotations without contradicting them.

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?

Four concise sentences, each carrying essential information. The main purpose is first, then routing to the sibling, then output details, then plan requirements. No filler, well-front-loaded.

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 output schema exists and annotations cover the safety profile, the description is complete. It explains the ranking, the candidate structure, and enrichment levels, and even notes the minimum plan. An agent has everything needed to call this tool correctly and understand its results.

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%, so the baseline is 3. The description adds context by explaining that the query accepts partial text and that candidates include postal lines, which enriches the meaning of the parameters. It doesn't rehash every schema field but adds enough to clarify usage beyond the bare 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 states a specific action (search French addresses from free text), a clear scope (French addresses, partial text), and the output (ranked candidates with a relevance score). It also distinguishes itself from verify_address by naming the sibling explicitly, making it 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?

The description explicitly recommends verify_address for confirming a single precise address, clearly routing the agent when to use this tool vs. the alternative. It also mentions the minimum plan required (Discovery), giving actionable selection criteria.

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?

The description is rich: it always returns an establishment, explains grouping, diffusible masking, and empty-result semantics. However, it asserts 'Une liste vide fait autorité : aucune entreprise ne correspond', which is a closed-world claim that contradicts the openWorldHint=true annotation. Per the rubric, a contradiction forces a score of 1.

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?

Dense but efficient: every sentence carries a distinct operational caveat or routing instruction, and the main purpose is front-loaded. There is no filler or repetition of schema text.

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 13-parameter, 0-required tool with an output schema, the description covers search modes, defaults, semantic interpretation of results, legal masking, empty results, plan requirements, and the next-step tool. Nothing needed 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: default result grouping for query vs siren/proximity, how to force it with group_by_company, and plan restrictions on proximity parameters.

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 specific verb and resource: searching French companies and establishments in the INSEE SIRENE base, and it lists concrete search criteria (name, SIREN, SIRET, city, postal code, NAF code, proximity). This clearly distinguishes it from sibling address/locality tools and from get_company_details.

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 gives clear usage context: default grouping behavior for query vs proximity vs siren, the Growth plan requirement for proximity search, and the follow-up tool get_company_details for the full record. It does not explicitly state when to prefer sibling search tools such as search_address or search_nearby, so it stops short of a 5.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds further context: returned fields (code INSEE, code postal, population, and details depending on plan), automatic normalization of names, and the Discovery plan minimum requirement. This goes beyond what annotations alone provide.

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 dense but well organized: two numbered use cases, one illustrative example, a preference note, and a return-field summary. Every sentence earns its place, and the core purpose is front-loaded.

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 0-required-parameter tool with a rich schema, an output schema, and clear annotations, the description covers all important invocation aspects: input modes, filtering options, output content, and the plan requirement. An agent has enough context to select and call the tool 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 coverage is 100%, so the baseline is 3. The description adds cross-parameter meaning: query is optional when a filter is present, department_code is preferred over department_name, and the population_min example clarifies combined usage. This is meaningful added value, though it does not enrich every parameter individually.

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 specific verb and resource: 'Recherche ET liste des communes françaises'. It also separates two distinct usages (precise lookup via query vs list/filter by department/region), which is especially useful for an agent distinguishing this from sibling address/company search 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 explicitly defines when to use query ('retrouver une commune précise') and when it is useless ('query est alors inutile' for listing/filtering). It gives a concrete worked example, advises preferring department_code over names, and notes automatic normalization of department names. Internal routing between the two modes is fully explicit.

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 mark the tool as read-only, idempotent, open-world, and non-destructive, but the description adds substantial behavioral detail: addresses are resolved like verify_address, results carry distance_m, enrichments follow plan tiers including statistical_grid Filosofi, pagination semantics are explained (next_offset, total_estime, tronque), and a 5000-result cap is disclosed. This goes well 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 opens with the core purpose in the first sentence, then efficiently covers center modes, result contents, pagination, truncation, and plan requirements. Every sentence contributes distinct information and none is redundant with 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?

For a 6-parameter spatial search with pagination, center-mode exclusivity, a 5000-address cap, and plan restrictions, the description is complete. An output schema exists, so the description does not need to enumerate return fields, but it still explains the crucial output concepts like distance ordering, resolved address, and truncated pagination.

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 each parameter already has a meaningful schema description, so the baseline is 3. The description adds further value by explaining radius units and range (1–50,000 m), reinforcing address/lat+lon exclusivity, describing how address resolution appears in point_central.adresse_resolue, and clarifying the pagination contract for offset. This is more than the schema alone provides.

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 a specific verb and resource: searching BAN addresses within a radius around a center point, sorted by distance. It clearly distinguishes the tool's spatial-search scope from siblings like search_address or verify_address by emphasizing the radial proximity and center-point modes.

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 clearly explains when to use this tool: to find addresses within a radius of a center, with explicit constraints on center modes and pagination. It does not explicitly name alternative tools or state 'use X instead', but the context is unambiguous and includes practical guidance such as reducing the radius when truncation occurs.

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, idempotentHint, and destructiveHint=false, and the description adds meaningful behavior: the verdict taxonomy, canonical line labels, plan-dependent enrichment (GPS/Lambert 93, IRIS, Filosofi statistical_grid), and the one-address-per-call constraint. No statement contradicts 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 main purpose is front-loaded in the first sentence, followed by output behavior, plan-tier extras, and the per-call limit. The plan-tier enumeration is somewhat long but earns its place by telling the agent exactly what to expect from `details`. The structure is logical, though not as tight as a two-sentence definition.

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 rich annotations, full schema coverage, and a present output schema, the description supplies the key missing context: BAN verification, verdict behavior, postal-line outputs, plan-based variance, and the single-address constraint. It does not explicitly contrast with overlapping siblings like get_address_details or search_address, but its distinctive vocabulary makes correct selection likely.

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?

Parameter descriptions in the schema already cover 100% of the three parameters, so the baseline is 3. The description goes slightly beyond by imposing 'Une adresse par appel' and by tying the `details` parameter to plan-dependent blocks such as statistical_grid. It doesn't re-document parameters, but adds the operational constraints that matter.

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 'Vérifie et normalise une adresse française contre le référentiel géographique officiel (BAN)', a precise verb-resource-target statement. It distinguishes itself from siblings by naming verdict types (match_exact, match_probable, aucun_match) and a canonical three-line postal output. 'Une adresse par appel' further clarifies its single-item verification scope.

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 clearly describes the use case: verifying/normalizing one French address against the official BAN and returning ready-to-use postal lines. The instruction to use ligne_voie/ligne_complement/ligne_commune as-is rather than recomposing the address is practical guidance. It doesn't name alternatives or exclusions, but the context is sufficient to differentiate from search/detail siblings.

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?

Goes far beyond the readOnly/idempotent/non-destructive annotations, disclosing subtle calculation rules such as `exclusif` being 'zone minus the union of all others' rather than 'total minus pairs'. It also exposes edge cases: unreachable zones return zeros and rank last, traffic peak may answer 'indisponible', and attribution must accompany every cited figure.

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 long but every sentence adds density and non-obvious semantics; there is no filler. It front-loads the core purpose and the distinctive outputs (`exclusif`, `chevauchements`, `classement`) before drilling into per-zone arguments and caveats.

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?

Covers output structure, parameter semantics, edge cases, reference behavior, attribution, billing, plan requirement, and performance — enough for an agent to invoke the tool correctly without external documentation. The presence of an output schema lets the description focus on interpretation and fallback rules rather than raw return fields.

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?

Despite 100% schema coverage, the description adds substantial meaning: `coefficient` triggers `potentiel_theorique`, `reference` is a single setting affecting both `csp` and `activites` indices, and `rank_by` values are enumerated with `coefficient` prerequisites. It also clarifies the address/lat-lon and minutes/radius_km exclusions and the `id` fallback behavior.

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: 'Compare de 2 à 10 zones de chalandise en un seul appel et mesure leur cannibalisation'. It clearly differentiates itself from the sibling `zone_stats` by positioning the multi-zone comparison and overlap analysis as its unique job.

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?

Explicitly references `zone_stats` as the tool whose output shape and block semantics are reused, which orients the agent to the single-zone alternative. It also gives operational guidance: plan minimum Growth, one call billed regardless of zone count, and expected runtime for ten isochrones.

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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: estimates vs measures, rounding behavior, null semantics, fiabilite fields, secret statistique imputation, DVF coverage gaps, NAF limitations, and the fact that zero inhabitants returns zeros not errors. It also warns against misinterpreting indices and reconstructing them. This far exceeds what annotations provide.

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 extremely long and dense, covering many blocks and edge cases. It is well-structured with clear block names and version markers, but it is far from concise. Every sentence adds value, but the sheer volume makes it hard to parse quickly. It is front-loaded with the core purpose, but the later blocks (immobilier, activites) are lengthy. A 3 reflects that it earns its length but is not concise.

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 (9 optional parameters, many output blocks, multiple version-dependent fields, estimation caveats), the description is remarkably complete. It covers return values, null semantics, fiabilite fields, reference handling, and usage constraints. The output schema exists, so return values are documented, but the description adds the interpretation guidance that an agent needs to use the data correctly. Nothing critical 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?

Schema description coverage is 100%, so the schema already documents all 9 parameters. The description adds meaningful context beyond the schema: the exclusivity rules (address vs lat/lon, minutes vs radius_km), the traffic=peak modeling details, the coefficient semantics with a concrete example (restauration ≈ 0.048), and the reference parameter affecting both csp and activites blocks. It doesn't repeat the schema verbatim but enriches it.

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 clear statement of what the tool returns: INSEE statistics about people living in a catchment zone, listing the main fields. It distinguishes itself from siblings by focusing on zone statistics rather than routing or address/company search. The title and description align well.

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 explicitly explains how to define the zone (minutes+mode+traffic vs radius_km, address vs lat/lon), when to use which parameter, and what happens with edge cases (no inhabitants, peak unavailable). It also mentions the plan minimum and that one call counts regardless of scope. It doesn't explicitly name sibling alternatives, but the parameter guidance is thorough and the tool's scope is clear.

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