insourcia

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

The description enriches the annotations substantially. It refines idempotentHint=true by explaining the exact semantics: same name + ACTIVE status → returned as-is with already_exists=true, no duplicate, no modification to the alert. It also details the enable_alert behavior (daily notification, initial 90-day recap, future entries only). All of this is genuinely additive beyond the bare idempotentHint=true flag and consistent with readOnlyHint=false/destructiveHint=false.

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 tightly structured: purpose, when-to-use, Fonctionnement (behavior/idempotency/alerts), then the response shape in a clear code-style block. Every paragraph earns its place for a tool with 43 parameters and nuanced idempotent and alert semantics. The most important decision-relevant info (what it does, when to use) 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 tool of this complexity the description is remarkably complete: purpose, usage routing, idempotency semantics, alert lifecycle, parameter model cross-reference, and the full response shape (id, name, url, result_count, filters, already_exists, alert_enabled). The output schema covers return values, and the 98%-coverage schema handles parameter specifics, so nothing an agent needs 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 98%, so the schema already carries the heavy lifting — baseline is 3. The description adds real conceptual value on top: it consolidates 40+ parameters into a mental model ('les filtres acceptes sont les MEMES que search_companies... groupe + advanced_filters JSON'), states the 'at least one criterion required' rule, and explains enable_alert's meaning in prose rather than as a bare boolean. That pushes it above the schema-only 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 specific verb and resource: 'Creation d'une recherche sauvegardee pour l'utilisateur', plus the concrete UI destination (page /news - Veille). It differentiates itself from the sibling search_companies by contrasting 'saving a search to track over time' vs 'one-off search', so an agent can tell the tools apart without inspecting 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?

Explicit and complete: 'Utiliser cet outil quand l'utilisateur veut SAUVEGARDER une recherche... pas pour une recherche ponctuelle (utiliser search_companies)'. Names the alternative tool directly and gives concrete example use-cases (veille marche, suivi de secteur, pipeline de cibles). Nothing is left 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?

The description goes far beyond the readOnly/idempotent/destructive annotations, adding rich behavioral context: Bilan K vs C comparability caveats, section-by-section null semantics ('Absent = independante', 'Null si aucune'), conditional data availability for listed vs unlisted companies, and the distinction between parent_direct/ultime and societe_mere sources. No contradiction with annotations exists.

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?

Although long, the description is highly structured with numbered content sections and front-loaded purpose and usage guidance. Each section adds distinct value, and the many null/absence caveats earn their place by preventing misinterpretation of the response.

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?

The description is exceptionally complete for a complex data-rich tool: it covers the full response structure, field availability conditions, financial comparability warnings, related tools, and null semantics. With an output schema present, return-value documentation is not needed, and this description still exceeds expectations.

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 input schema already documents both siren and include_fields well. The description adds minimal parameter-specific meaning beyond identifying the company by SIREN and emphasizing 'one company at a time'; it does not elaborate on include_fields beyond what the schema already provides. Baseline 3 is appropriate.

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, specific statement: it returns the complete record of a French company identified by its SIREN. It distinguishes itself from siblings by explicitly limiting scope to one company at a time and naming deeper-dive alternatives like get_financials, get_directors, and get_events.

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 says to use this tool for one company at a time and points to watch_company for monitoring and get_financials/get_directors/get_events for deeper analysis. It lacks an explicit statement about what to use for multiple companies (e.g., search_companies), so it is clear but not fully exhaustive in routing to alternatives.

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 discloses substantial behavior beyond the read-only annotations: orientation and edge types, exclusion of commissaires aux comptes, expansion rules and their pitfalls, hub-director guard, node caps, truncation reporting, and lack of detention percentages. This is exactly the kind of behavior an agent needs to interpret unexpected or partial results.

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 the complexity of the tool justifies it. It is well-structured with clear sections for response shape, key behaviors, and filters, and is front-loaded with the core purpose before moving to edge cases. A little trimming could improve scannability, 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?

Given the graph tool's complexity, the description is remarkably complete: it covers node ID formats, edge types, defaults, expansion behavior, guardrails, truncation notification, and filter semantics. Even with an output schema present, the description adds the interpretive knowledge needed to use the graph 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, but the description adds meaningful context for depth, expand_persons, and filters: what depth levels actually traverse, when expand_persons=false yields a purely capitalist graph, and that the root is never filtered. It does not merely restate 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 opens with a precise statement of what the tool does: maps entities around one company by SIREN as a directed, typed graph. It further names sibling alternatives get_directors and search_director_companies, clarifying how this tool differs from entity-detail and person-footprint 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?

It explicitly states when to use the tool ('visualiser ou analyser la structure d'un groupe') and what it complements, giving concrete sibling alternatives and their scopes. The filter descriptions and expansion rules also give actionable guidance on how to tailor the call.

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 annotations already mark it as read-only and idempotent; the description adds useful behavioral detail beyond that, including the three possible response shapes, the 404 error for unknown SIRENs, and the Pro plan restriction. This gives the agent a clear picture of edge cases without contradicting 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 well-structured, front-loads the core behavior, and uses bullets for the concrete response variants. Every line earns its place: scope, output, response shapes, error case, plan restriction, and usage guidance.

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 simple one-parameter tool with an output schema already present, the description covers all essential context: input format, output semantics, non-scored companies, unknown-SIREN handling, access restriction, and the intended use case. Nothing critical is missing for a 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?

The input schema is fully documented with one required parameter (siren) and its description 'SIREN a 9 chiffres.' The tool description reinforces that the SIREN identifies a French company but adds no new parameter-level meaning beyond what the schema already 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 states the tool's exact purpose: scoring a single French company by SIREN and returning its credit risk grade, default probabilities, and top factors. It is unambiguous and clearly distinct from sibling tools such as get_company or get_financials, which do not focus on credit risk.

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 to use it for one company at a time and names the primary use cases (supplier risk / due diligence). It does not explicitly mention when to prefer sibling tools, but the specialized nature of the endpoint makes the intended usage clear.

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 this as read-only and idempotent, and the description adds substantial behavioral detail: sorting by importance, inclusion of CACs, the PP/PM structure, nested representatives, active-vs-inactive filtering, and the one-company constraint. It discloses what the caller should expect beyond the schema.

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 well-structured with a clear summary, useful bullet points, and a front-loaded purpose. It is longer than necessary in places, such as repeating the include_inactive behavior already present in the schema, but every section contributes useful context.

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?

The description is complete for a single-company directors tool: it explains the required SIREN, the response structure, sorting, active/inactive behavior, CAC inclusion, and confirms one company per call. With an output schema present and annotations covering safety, nothing essential 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 siren, limit, offset, and include_inactive. The description restates the default active-only behavior but does not add significant new parameter-level semantics; it mainly details the output shape, which is covered by the output 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 opens with a clear verb and resource: it details the directors of a company with hierarchical structure. It further specifies the two entry types (PP/PM), notes that results are ordered by importance, and closes with 'one company at a time,' which helps distinguish it from sibling 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 gives practical context: it is for a single company, active directors are returned by default, and include_inactive=true adds history. It does not explicitly name an alternative like search_directors or state when that sibling should be used, so it stops short of full exclusion 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses meaningful behavioral details: it merges cessions[], procedures[], and scalar dates into a single descending chronological timeline. This explains the tool's output semantics in a way annotations alone do not.

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: the first line states the core purpose, the second clarifies the data fusion behavior, and the third gives usage guidance. Every sentence earns its place with no redundant wording.

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?

The description covers the tool's scope, merge behavior, ordering, single-company constraint, and the alternative for broader searches. Since an output schema exists, the description does not need to enumerate return fields, and the input schema already documents parameters.

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 six parameters. The description adds some semantic context about SIREN scoping and chronological ordering, but it does not need to describe each parameter in detail.

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 provides a unified timeline of events for one company by SIREN, and explicitly distinguishes it from search_events for cross-SIREN prospecting. The verb 'fusionne' and the resource 'evenements d'UNE entreprise' make the purpose specific and actionable.

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 explicitly states when to use this tool ('une entreprise a la fois') and directs users to search_events for cross-SIREN prospecting. This is direct, unambiguous routing to the correct sibling 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 mark the call as read-only/idempotent/non-destructive, and the description adds substantial context beyond that: plan-gated 403s, mode defaults by plan, null semantics for missing items, the _layout structure, sector-specific plan nuances, and euro units. This is rich behavioral disclosure that fully carries its weight.

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?

Although the description is long, it is well-structured into distinct mode blocks and front-loaded with the core purpose. Each section—compact, full, fields, ifrs, and _layout—provides invocation-relevant information, and the formatting makes scanning easy.

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 that an output schema exists, the description did not need to explain return values, yet it still documents _layout, null behavior, source caveats, and failure modes like 403 on free plans. Combined with full schema coverage and read-only annotations, an agent has everything needed to select and invoke 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, but the description adds meaningful semantics: field-count implications of compact vs full, free/pro limits on fields, categories of available fields, and the conditional ifrs block. It materially improves an agent's ability to choose parameter values beyond the schema's enum and format descriptions.

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 identifies the resource and operation: 'Historique financier détaillé d'une entreprise sur plusieurs exercices' and later uses verbs like 'retourne TOUS les champs financiers disponibles'. It is distinct from sibling tools such as get_company or get_credit_risk, which cover different data domains.

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 gives strong internal usage guidance: plan-aware defaults, free-plan 403 behavior on full mode, and the explicit recommendation to use fields for 1-5 additional ratios. It does not name alternative sibling tools or state explicit when-to-use/exclusions relative to them, so it falls just 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond this: merged/deduplicated results sorted newest first, detection date vs effective date, truncated semantics, partial count floors, Free-plan hidden signals, and the fact that an empty news array is not an error.

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 longer than average but nearly every sentence carries operational value: purpose, usage, data composition, parameter caveats, and edge cases. It is front-loaded with the main purpose and usage, though a bit dense toward the end.

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?

The description covers response shape, filtering, read/unread semantics, read_key usage with mark_news_read, truncation, partial counts, plan limitations, and empty-result handling. Given an output schema is present and the tool has four optional parameters, nothing essential is missing for 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 the schema already documents all parameters with defaults and limits. The description adds some operational context for since_days and event_types by linking them to truncation and narrowing, but it does not add significant parameter-level meaning beyond what the schema 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 states a specific verb and resource: a daily news feed of the user's watched companies as shown on the /news page. It further distinguishes itself from broader siblings by specifying that it merges and deduplicates real alerts plus watchlist activity across all spaces, which separates it from get_events or search_events.

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 gives explicit use cases: answering 'quoi de neuf sur ma veille ?', summarizing weekly updates, or before drafting a weekly report. It does not explicitly name alternative tools or state when not to use it, but the context and domain are clear enough for an agent to route correctly.

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?

Although annotations already cover read-only, idempotent, and non-destructive behavior, the description adds valuable details: the exact response shape, field-level semantics (filters normalized, result_count nullable, alert_enabled), sorting order (most recent first), and empty-list meaning (no watches configured). This goes beyond the structured annotations and helps the agent interpret results correctly.

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 well-structured and economical: a one-line purpose, concise usage bullets, and a compact response shape. Every sentence contributes value, and the key context is front-loaded. There is no fluff or redundant restatement of the tool name or 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?

For a simple read-only list tool with one optional parameter, annotations, and an output schema, the description covers all necessary context: when to use, what it returns, field semantics, sorting, and empty behavior. Nothing needed to invoke or interpret the result 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 for the single limit parameter is 100%, and the schema already documents its default and bounds. The description does not add new parameter-level meaning, so the baseline of 3 is appropriate. There are no undocumented parameters requiring compensation.

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 begins with a specific verb-resource pair: 'Liste des recherches sauvegardees de l'utilisateur', clearly identifying this as the user's saved searches within the /news monitoring page. This distinguishes it from siblings like create_saved_search (creation), list_watched_companies (different resource), and get_news (news content). The purpose is immediately understandable and 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 says 'Utiliser cet outil' and gives concrete scenarios: before create_saved_search to avoid duplicate watches, and to answer questions like 'quelles veilles ai-je ?'. This directly names an alternative and the condition that selects this tool, which is exactly what an agent needs.

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 goes well beyond the readOnlyHint and destructiveHint annotations. It explains that a non-matching list_name returns companies: [] and total: 0 rather than an error, that omitting list_name returns all lists, that results are flattened and sorted newest first, and it details the response fields. This is rich behavioral context.

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 well-structured with a clear purpose, bulleted usage cases, parameter behavior, and a response format section. It is somewhat detailed but every section carries useful information; no fluff or redundancy beyond a minor overlap with the schema's list_name 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?

The description covers all essential context: purpose, usage timing, optional parameter behavior, invalid-input behavior, response structure, ordering, and even the relevant app page. Nothing an agent needs to call this tool 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 schema already documents list_name. The description adds meaningful edge-case behavior: an unmatched list_name is not an error, and omission means all lists. This exceeds the baseline but is not needed for basic parameter understanding.

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 and resource: 'Liste des societes surveillees par l'utilisateur dans ses listes de veille'. It also ties the tool to a concrete app page (/lists) and gives example user questions, making the tool's purpose immediately clear and distinct from siblings like list_saved_searches.

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 says when to use the tool: before watch_company, and to answer questions about watched companies or list contents. It does not explicitly mention when not to use it or compare it to list_saved_searches, but the usage context is strong enough to guide selection.

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?

Beyond the annotations (idempotentHint, destructiveHint), the description details how idempotency manifests (already-read keys counted in already_read), what is preserved (line remains visible, last visit unchanged), and what the response contains. It also discloses the non-reconstructible key format, which agents need to know before calling.

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 front-loaded with purpose and usage triggers, then organized into tight bullets for behavior and response. No sentence is filler; each bullet conveys a distinct operational fact an agent must know.

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 one-parameter mutation with output schema and strong annotations, the description covers invocation source, idempotency, side effects, limits, and return fields. There is no missing information needed to call it correctly or to set user expectations.

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 already 100% and covers max 500 items and the read_key provenance. The description adds practical meaning by stressing 'telles quelles' and explaining that key format varies by signal type and is not reconstructible, which strongly guides correct invocation.

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 action ('Marque comme lus') and a precise resource ('signaux precis de la veille... page /news'), and its scope is differentiated from sibling get_news by referencing read_keys returned by get_news. It is immediately clear this is the state-change counterpart to a read operation, not a search or list tool.

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 explicit trigger phrases ('ok j'ai vu', 'marque-les comme lus') and states when not to use it: there is intentionally no mark-all behavior, so agents should not attempt bulk clearing. It also clarifies that the tool does not update last-visit date, preventing incorrect use for that purpose.

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, but the description adds rich behavior beyond those: the tool REFUSES to decide when unsure, returns per-record statuses, explains each review reason including lookup_failed as a replayable technical failure rather than a no-match, and preserves input order. 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 long but each paragraph earns its place: usage routing, behavioral distinction, status semantics, reason codes, data-quality guidance, identifier shortcut, and return shape. It is front-loaded with the core purpose and structured so an agent can quickly extract routing and status behavior.

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 batch tool with one complex parameter and an output schema, the description fully covers what an agent needs to decide when to use it and what responses to expect: statuses, reasons, order preservation, summary fields, and exploitability indicator. Nothing material 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 describes every field, so the baseline is 3. The description adds genuine value by explaining that an existing siren/siret/TVA is resolved without lookup, that siret uses the first 9 digits, that id is never used for matching, and that postal_code is the strongest non-identifier signal. This goes beyond the schema's per-field descriptions.

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: batch reconciliation of poorly identified records to SIREN. It clearly distinguishes itself from search_companies by contrasting 'liste de sociétés' with 'UNE société cherchée par son nom' and by noting this tool returns a decision rather than ranked results.

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 states when to use this tool: when the user has a LIST of companies to identify, with concrete example phrasings. It explicitly directs single-company lookups to search_companies and explains the behavioral difference, including refusing to decide when uncertain.

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 discloses many behavioral details not covered by annotations: unknown keys in advanced_filters are rejected (400), include_fields is limited to 3 on free and 10 on pro, pagination is Pro-only, default 20 results, _user_plan is returned, and results are sorted by relevance. It also explains that a company in collective procedure remains ACTIVE until radiation, and clarifies that date_radiation is missing for ~9.9M companies, providing deep transparency about edge cases.

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 highly detailed but somewhat verbose, with repeated mentions of include_fields mappings (twice) and plan limits. However, it is well-structured with clear sections (FILTRES, TRI, retour) and front-loads the primary use case, making it scannable despite length. The redundancy is minor and does not detract from usability.

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?

The description is comprehensive for the tool's complexity: it lists the default return fields, explains plan-specific limitations (free vs pro), mentions pagination cursor usage, and provides an example flow (search → get_company/get_financials). It also covers advanced topics like groupe filtering, director disambiguation, and edge cases (e.g., status vs. procedure), leaving no obvious gaps for an agent to misuse the 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?

While the input schema already provides descriptions for each parameter, the tool description adds significant semantic layers: mappings for include_fields (e.g., dividendes_min→dividendes_verses), clarification of advanced_filters key handling, and differentiation between declared groups (siren_groupe) and inferred ones (groupe_pont_siren). The description also explains the interaction between parameters (e.g., radius requires latitude+longitude) and provides examples for enums.

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 that the tool searches French companies by name, SIREN, activity, and financial criteria, and provides a specific use case (find SIREN then use get_company). It explicitly differentiates from search_director_companies by describing the direct vs. indirect mandate scope, making the purpose distinct and 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?

Extensive usage guidance is provided: when to use this tool first (e.g., for company info by name), how to combine filters, sorting examples, pagination limits, plan-specific behavior, and an explicit recommendation to prefer search_director_companies for direct mandates. The description also notes non-available filters (LinkedIn) and gives concrete examples for sort_by and sort_order.

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 provide readOnly/idempotent/non-destructive hints, and the description adds valuable behavior: only direct mandates are returned, resolved_from_pm entities are excluded, and an empty result means no direct mandate for that exact identity. It also documents the response shape and pagination, going well beyond the annotation metadata.

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?

Although long, the description is efficiently structured: purpose first, then usage guidance, then parameters, response format, and exclusions. Every sentence contributes distinct information; none are 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?

For a read-oriented search tool with an output schema, rich annotations, and 100% parameter schema coverage, the description covers the use case, prerequisites, response contract, edge cases, and scope boundaries. Nothing an agent needs to select and invoke 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 description coverage is 100% and each parameter already has a description including the YYYY-MM-DD format and disambiguation role. The prose repeats the requirement that date_naissance is mandatory but does not add substantial new meaning beyond the schema, so 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 opens with a precise verb and resource: mapping the corporate footprint of one natural person via all companies where they hold a direct mandate, disambiguated by exact name and birth date. It explicitly contrasts with search_directors and get_directors, 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?

It states when to use the tool (M&A perimeter tracing), why date_naissance is mandatory and how to obtain it first via search_directors or get_directors, and what not to use it for (broader search_companies with resolved_from_pm). This is explicit routing to alternatives with exclusions.

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?

Beyond the readOnly/idempotent annotations, it discloses meaningful behaviors: only active mandates are returned by default, include_inactive=true changes that, homonyms are disambiguated by date/lieu de naissance, and pagination.total counts matching companies rather than people. 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 main purpose is front-loaded and each paragraph has a clear role: sibling differentiation, parameter behavior, response shape, homonym handling, and chaining to other tools. It is long but dense; slight redundancy with the schema and output details prevents a 5.

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?

The description is complete for this tool's complexity: it covers scope, required parameters, defaults, homonym pitfalls, pagination semantics, and onward paths to sibling tools. Given the annotations and output schema, nothing essential is missing for 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?

The input schema already documents all 5 parameters at 100% coverage, so the baseline is 3. The description adds useful nuance: nom is required, prenom is for disambiguation, role gets concrete examples, and include_inactive is linked to the default active-only behavior. This elevates it above baseline, though it mostly restates schema details.

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 states a specific action ('Recherche de personnes (dirigeants)') across all French companies by surname. It explicitly contrasts with search_companies, which returns companies, making the purpose and sibling distinction unmistakable.

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 concrete routing guidance: use search_directors to find people/directors by name, use search_director_companies to list all companies for a known person once the birth date is known, and use get_directors for a full company-director record via SIREN. It also distinguishes itself from search_companies, so an agent can choose correctly.

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 indicate readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond this: the output shape, the underlying ES index, the BODACC/silver scalar sources, the unconditional 400 error when the filter rule is violated, and the fact that events are returned individually rather than as companies.

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 section earns its place: purpose, return shape, event types, data sources, the mandatory filter rule, and practical examples. It is front-loaded with the most important information and the examples are compact and immediately actionable.

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 (14 parameters, conditional filter requirement) and the presence of an output schema, the description is complete enough for an agent to call it correctly. It covers what the tool returns, which filters are mandatory, what event types exist, and how to translate real-world requests into valid parameters.

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 parameter-usage context by grouping filters, showing examples like type='cession' with region, date_min, and prix_min, and clarifying that certain filters apply to specific event categories (cession, procedure). This goes beyond the individual schema descriptions.

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 ('Recherche'), a resource ('evenements d'entreprise cross-SIREN'), and clearly states that it returns individual events, not companies. It also enumerates the 8 event types, which makes it easy to distinguish from company-level search tools like search_companies.

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 gives a hard invocation rule (at least one of region/departement/code_naf OR an event filter must be provided, otherwise 400) and provides concrete natural-language-to-parameters use cases. It does not explicitly contrast with get_events or state when not to use this tool, but the contextual guidance is strong.

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 adds substantial behavioral detail beyond the annotations: omission of list_name removes from all lists, the operation is idempotent and returns removed=false when absent, the list itself is never deleted, alerts remain active, and removal works even for companies missing from the index. These details are not present in the annotations and are critical for correct use.

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 longer than average but well-organized with a usage line, bulleted behavior, and response shape, all relevant to correct invocation. It loses a point because the response format is largely redundant with the existing output 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?

All edge cases an agent needs to handle are covered: absent company, missing list, empty list, active alerts, and cross-list removal. With the output schema present and the behavioral bullets, nothing essential is missing for 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?

The schema already documents both parameters thoroughly with 100% coverage, including the exact-name requirement and the omission behavior for list_name. The description largely repeats this information rather than adding new parameter-level semantics, so the baseline of 3 is appropriate.

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: removing a company from watchlists, tied to the /lists page. It identifies the tool as the inverse of watch_company, making it clearly distinguishable from the sibling tool without needing to open 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?

It explicitly states when to use the tool: whenever the user wants to stop following a company, with concrete phrasings such as 'je ne suis plus interesse par X' and 'enleve X de ma veille'. It also points to list_watched_companies as the way to obtain exact list names, covering prerequisites and alternatives.

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 goes well beyond the annotations by explaining exactly what happens: auto-creation of lists, idempotent behavior with already_watched=true, daily alert semantics, future-only events with no history replay, and the response shape. It also aligns with idempotentHint=true and provides practical consequences of enabling alerts.

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 front-loaded with purpose, then gives clear usage guidance, a labeled 'Fonctionnement' section, and a concise response outline. It is detailed but every sentence contributes meaningful behavioral or selection information, and the structure makes it easy to scan.

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?

The description covers the main use case, alternatives, parameter behavior, alert semantics, idempotency, response fields, and the Insourcia UI context. Given the tool's moderate complexity and the presence of a complete output schema, nothing essential is missing for an agent to call it 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 value beyond the schema by explaining list_name as the target list, clarifying that any named list is auto-created, and detailing that enable_alert triggers a daily digest of future BODACC and director-change events. This is more than the schema alone provides, though not substantially more on the siren 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?

The description opens with a specific verb and resource: 'Mise sous surveillance d'une societe' and 'l'ajoute a une liste de veille'. It clearly distinguishes the tool from get_company by stating this is for following a company over time, not simple consultation.

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 states when to use the tool: 'Utiliser cet outil quand l'utilisateur veut SUIVRE une societe dans le temps', and names the alternative for the excluded case: 'pas pour une simple consultation (utiliser get_company)'. This leaves no ambiguity about tool selection.

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