Ilicompta — experts-comptables en France

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

Annotations already declare read-only/idempotent/non-destructive, yet the description adds substantive behavior: the parser is deterministic and limited, it may return clarification_needed rather than partial results, and it specifies how to handle that outcome. It further discloses downstream obligations (read interpretation.matched, cite citation_url with evidence, disclaim that website mentions are not certifications) that no structured field conveys.

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 sentences, front-loaded with purpose before behavior and routing. The final clause about citing citation_url and disclaiming certifications borders on output-format guidance that a present output schema partly duplicates, but it is still actionable and not wasted space.

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 natural-language parsing tool with an output schema, rich annotations, and a non-obvious failure mode, the description covers the critical gaps: the clarification path, the fallback sibling, and the evidence/disclaimer expectations. 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 67%, and the description meaningfully extends the `request` parameter by explaining what it cannot represent (negations, multiple values, conflicting locations) and that unrecognized criteria are never assumed satisfied. It says nothing about `city` or `limit`, but those are covered by the schema or are self-evident bounded integers, so the added value still exceeds 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?

States a concrete verb chain (parse a natural-language request, search the public catalog with AND filters) and names the exact input domain (French/English accounting requests). It explicitly contrasts itself with search_cabinets and get_taxonomies, so an agent can distinguish it from siblings without opening schemas.

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?

Gives explicit routing rules: use this for natural-language requests, prefer search_cabinets with get_taxonomies for exact filters and firm names. It also states a when-not/never rule ('never retry by dropping their requirements') for the clarification path, leaving nothing to inference.

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 genuinely useful behavioral context beyond them: unknown dates are made explicit rather than omitted, and the data is explicitly uncertified ("à confirmer, sans certification de compétence"), which tells the agent how to caveat the values it reads.

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, front-loaded with the verb and field list, followed by two caveats that each carry real information. The telegraphic fragments ("Dates inconnues explicites") are terse to the point of ambiguity, which slightly undercuts readability, but nothing is redundant.

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 structure need not be restated, and annotations cover the safety profile; the description fills the remaining gaps (where the key comes from, data reliability caveats, field coverage). Missing only failure behavior for an invalid or unknown slug, which would matter for a lookup-by-key tool.

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 0%, so the schema only supplies a pattern and length constraint for `slug`. The description compensates by explaining the parameter's provenance and contract — it is a lookup key obtained from search_cabinets — which is the single most important thing an agent needs to satisfy the required parameter.

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?

Names a specific verb and resource ("Lire une fiche par slug") and enumerates exactly what the record contains: identity, address, legal information, activities, sources, canonical URL. It also distinguishes itself from the sibling tool by stating the slug comes from search_cabinets, so an agent can separate this read-by-key tool from the search tool without opening either 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 phrase "slug obtenu dans search_cabinets" establishes the prerequisite step and effectively routes the agent to search first, then fetch by slug. It stops short of explicit exclusions (e.g., what to do when a slug is stale or the record is absent), so it is clear context rather than full 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 closed-world, so the safety profile is covered. The description adds genuine value beyond that by disclosing the return contents (coverage, denominators, city page URL) and warning that the figures are partial counts, not market share or a full census.

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 tight sentences: what it counts, what it returns, what it is not. The caveat is front-loaded with the core action rather than buried, and each sentence carries information an agent would otherwise guess wrong.

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 values need no explanation, and annotations carry the safety profile. Still missing are the input format for city and any routing guidance relative to resolve_city, which for a city-keyed lookup tool are the two gaps an agent is most likely to hit.

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 single 'city' parameter has 0% schema description coverage, so the description must compensate. It hints that arrondissements are folded in for Paris/Lyon/Marseille but never states the expected input form (plain name vs. arrondissement code vs. a resolve_city slug), leaving the one thing the agent must get right underspecified.

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: counting Ilicompta-indexed listings per city, with explicit handling of arrondissements for Paris, Lyon and Marseille. An agent can tell this apart from search_cabinets or find_accountants, though the description does not name those siblings to draw the contrast.

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 clarifies what the data is not (market share, exhaustive census), which prevents misreading, but gives no positive guidance on when to call this versus resolve_city or search_cabinets. Usage is only implied by the counting scope.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is low; the description still adds real semantic value by warning that vocabulary presence does not imply a firm has that capability, preventing a common over-inference. It does not describe the shape of the returned taxonomy, but the output schema covers that.

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, front-loaded with what is read, then the caveat, then the operational rule. No filler or restatement of the name.

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 zero params, full annotation coverage and an output schema, the definition needs only purpose plus caveats, both of which are present. A slightly stronger version would state the call ordering relative to search_cabinets explicitly.

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 there is nothing to disambiguate and the baseline is 4. The description correctly spends no space on parameter explanation.

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 (read) and a specific resource (the exact sector, service, software and language values accepted by search_cabinets), which also pins down the relationship to the sibling that consumes them. An agent can tell immediately this is a vocabulary lookup rather than a search.

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 establishes the context of use by tying the values to search_cabinets and adds a concrete rule ('never replace an unknown requested criterion with a broader category without user agreement'). It stops short of explicitly saying 'call this before search_cabinets to validate parameters', so the sequencing is left slightly implicit.

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, closed-world semantics, so the safety profile is covered. The description adds genuinely new behavior: candidates should be surfaced to the user rather than auto-selected, and there is no nearby-city expansion — a real scope constraint an agent would otherwise assume wrong.

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, each earning its place: what it returns, when to use it, and how to handle the result. The usage cue and the anti-pattern warning are front-loaded with zero 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?

Only two simple parameters and an output schema exists, so return-shape documentation is unnecessary. Usage, scope limits, and the handling policy are all covered; the only omission is guidance on `limit` and on the minimum query length/behavior for very short prefixes.

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 0%, so the description must carry parameter meaning. It does explain that `q` accepts a name prefix or a postal code, which is meaningful added semantics. However, `limit` is never mentioned in the description and its purpose must be inferred from the schema alone.

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 ('Find catalog city slugs') plus the two accepted input modes (name prefix or postal code). It implicitly separates itself from search/catalog siblings by framing the result as slugs for resolution rather than search results, though it never names a sibling 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?

'Use before searching when a locality is ambiguous' gives a clear triggering condition and ordering relative to downstream search tools. It stops short of stating when the tool should be skipped (e.g., when the user already supplied a known slug), but the intended workflow is unambiguous.

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, non-destructive, closed-world, so the safety profile is covered; the description still adds substantial non-obvious context: no quality ranking, no price or availability guarantees, website-level extraction is not a verified qualification, and unknown dates stay unknown. It also tells the agent which fields to cite (citation_url, evidence.source_url) and that visit_url is merely an optional navigation link.

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?

Front-loaded with the core action, then prerequisites, then constraints — a sensible information hierarchy. It is dense with operational rules and nearly every sentence earns its place, though the quoting/citation sentence is slightly compressed and mixes output guidance into the search description.

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-value explanation is not required, and the description instead adds sourcing and limitation caveats that the schema cannot express. The remaining gap is pagination and faceted-parameter behavior (limit/cursor, how sector vs service interact) for an 8-parameter, zero-required tool.

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 25% — only q and city are documented structurally — so the description carries real weight here. It reinforces q's limitation and points to get_taxonomies for valid category values (sector, service, language, software), but it never explains limit, cursor pagination, or what each faceted parameter accepts or how they combine. Useful compensation, but incomplete for a low-coverage 8-parameter 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?

States a specific verb and resource ('Search French accounting firms') plus the crucial scope qualifier 'by exact AND filters', which tells an agent this is a structured filter lookup rather than a free-text search. That qualifier alone distinguishes it from the sibling find_accountants and from get_cabinet's single-record lookup.

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 routes the agent to prerequisites: resolve_city for ambiguous locations and get_taxonomies for exact category values. It also gives a negative boundary ('q is a firm name or SIREN, never a service query') and a behavioral rule for the zero-result case ('do not remove a filter or widen the city without agreement'), which is exactly the guidance an agent needs to invoke this correctly.

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