insourcia

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

Beyond the annotations (idempotentHint=true), the description details the exact idempotent behavior: an existing active search with the same name is returned as-is with already_exists=true, no duplicate is created, and the existing alert is not modified. It also discloses the alert side effects: daily notifications, an initial 90-day recap, and only future matches triggering subsequent 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 well structured with a purpose statement, explicit usage guidance, a 'Fonctionnement' section, and a response summary. It is detailed enough for a 37-parameter tool but contains no filler; each section earns its place.

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 complex tool with rich schema and annotations, the description covers all necessary invocation context: when to use it, the idempotent behavior, alert consequences, the response shape including already_exists and result_count, and the post-creation action of sharing the URL with the user. 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 97%, so the schema carries most parameter documentation. The description adds valuable high-level semantics by stating that accepted filters are the same as search_companies, listing the filter families, and emphasizing that at least one criterion is required—a constraint not obvious from the schema's required fields 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?

The description opens with a specific verb and resource: 'Creation d'une recherche sauvegardee pour l'utilisateur, visible dans l'app Insourcia (page /news - Veille).' It also distinguishes itself from search_companies, so an agent can tell exactly which tool creates persistent saved searches versus one-off company 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 explicitly states when to use the tool—'quand l'utilisateur veut SAUVEGARDER une recherche pour la suivre dans le temps'—and explicitly says not to use it for one-off searches, directing the agent to search_companies instead. It also notes the minimum criterion requirement.

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 valuable behavioral context beyond annotations: the output is a comprehensive structured fiche, financial figures must always be labeled with year and type_bilan due to comparability caveats, absent group/fund/IFRS fields mean independence or no data, and the agent is expected to propose watch_company under the right conditions. 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 the length is largely justified because there is no output schema and the tool returns a very rich record. It is front-loaded with the core purpose, then organized into ten numbered sections with clear formatting instructions. The 'Suivi dans le temps' paragraph adds an actionable usage policy, though it is a bit tangential to the tool's own behavior, so the description is not perfectly 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?

For a complex retrieval tool with no output schema, the description is exceptionally complete: it defines the ten output sections, covers special cases like radiated companies, group membership absence, non-listed IFRS absence, private-equity ownership blocks, and public-data null states. It also tells the agent how to present results and where to route deeper follow-up queries. Nothing essential to calling the 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?

The input schema already documents all three parameters thoroughly: siren format, context purpose with word-count guidance, and include_fields examples with plan limits. Schema coverage is effectively 100%, so the baseline is 3. The description mostly reinforces the SIREN key and the include_fields parity concept but does not add significant new parameter semantics 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 opens with a precise verb and resource: 'Fiche complète d'une entreprise française identifiée par son SIREN.' It immediately indicates the tool returns a full company record for one SIREN, and it distinguishes itself from siblings by naming the focused alternatives get_financials, get_directors, get_events and the follow-up action watch_company.

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 pour une entreprise à la fois.' It also gives clear routing guidance: propose watch_company when the user shows durable interest, only with consent, and use get_financials/get_directors/get_events to get deeper multi-year, director, or event-level detail. This is explicit when-to-use and alternative 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?

The description goes far beyond the readOnlyHint/idempotent annotations by disclosing detailed behavioral traits: statutory auditors are excluded, IDs follow specific formats, shareholding percentages are unavailable, depth semantics govern expansion, hub-director detection prevents exploding the graph, and node/global caps produce truncations reported in meta.truncated. This is exceptional transparency and contains no contradiction with 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 but every section earns its place: purpose, usage, response format, key behavioral caveats, and filters. It is front-loaded with the core purpose and uses clear bullets and labels, making the density navigable. There is no redundant or filler 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?

Given the complexity of the tool, the description is remarkably complete: it explains edge types, node ID conventions, depth behavior, person expansion rules, hub-director logic, truncation caps, and all filter defaults. Because an output schema exists, return-value structure is already available, and the description complements it with the exact semantic details an agent needs to interpret 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?

Although the schema already covers 100% of parameters, the description adds substantial meaning: depth=1 vs depth=2 expansion behavior, expand_persons=false for capitalist-only graphs, caps like 20 subsidiaries and 40 companies per person, and the guarantee that the root is never filtered. This goes well beyond the baseline for full schema coverage by explaining how parameters interact with graph construction.

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: 'Cartographie des entites autour d'UNE entreprise (par SIREN)' and explicitly states the output is an oriented, typed graph built from RCS/RNE mandates and group links. It distinguishes itself from siblings by naming get_directors and search_director_companies as complementary tools with different scopes, so an agent can clearly identify what this tool uniquely provides.

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 tells the agent when to use this tool: 'Utiliser cet outil pour visualiser ou analyser la structure d'un groupe : holdings, filiales, societes soeurs, dirigeants communs.' It also names alternatives and their different purposes, and gives concrete guidance about when to disable expand_persons for a purely capitalist graph, which is exactly the kind of decision support 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?

Annotations already declare this as read-only and idempotent. The description adds meaningful behavioral context: possible response variants (scorable vs non-scorable), 404 for unknown SIREN, and restriction to Pro plan, which are not present in 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-organized with a clear front-loaded purpose, followed by return values, plan restriction, response shapes, and usage hint. Each sentence carries relevant information, though the response-shape list makes it slightly longer than strictly necessary.

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 two-parameter read-only tool with an output schema, the description covers the important operational cases: success, non-scorable company, and 404 error. It also notes the plan restriction and use cases, leaving little ambiguity for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%: both siren and context have full descriptions. The tool description only reinforces 'one company at a time' without adding new parameter-level detail, 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 clearly states the tool scores the credit risk of one French company by SIREN and lists specific returned outputs (risk grade, default probabilities, factors). This distinguishes it from sibling tools like get_company and get_financials.

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 says the tool is for one company at a time and names the target use cases: supplier risk and due diligence. It does not mention exclusions or compare itself to alternatives, but the context is 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?

Beyond the readOnly/idempotent annotations, the description discloses sorting by importance, default filtering to active mandataires, inclusion of CAC roles with mandate dates, and nested representants[] for PM entities. This gives the agent a clear expectation of what the tool returns and how it behaves.

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 bolded entity types, bullet-like field lists, and a clear flow from purpose to output shape to defaults to usage guidance. Every sentence adds useful information without redundancy.

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?

Combined with the output schema and annotations, the description is complete for selecting and invoking the tool: it specifies required context (single company), return structure, filtering behavior, and how to include history. 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 baseline is 3. The description reinforces include_inactive semantics and default behavior, but adds little beyond what the schema already states for parameters like siren, limit, and offset.

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 'Detail des dirigeants d'une entreprise avec structure hierarchique' and specifies that it returns directors sorted by importance, with PP and PM entity shapes. This clearly distinguishes it from sibling search tools by anchoring it to a single company via SIREN.

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 clear usage context: 'Utiliser cet outil pour une entreprise a la fois' and explains the active/inactive default behavior via include_inactive. It does not explicitly name alternatives or state when not to use sibling tools, but the single-company constraint and SIREN requirement provide solid 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, and non-destructive hints. The description adds valuable behavioral context beyond those hints: it discloses that the tool fuses cessions[], procedures[], and scalar dates into a single descending chronological stream. This gives the agent a clear model of the returned timeline's structure.

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: three sentences, with the core purpose and merging behavior front-loaded and the sibling alternative in the final sentence. Every sentence contributes meaningful routing or behavioral information with no 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 tool with a rich output schema, complete input schema, and safety annotations, the description covers the essential operational context: what events are merged, how they are ordered, the single-company constraint, and when to route to search_events. Nothing critical is missing for correct selection and 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 has 100% description coverage for all parameters, so the schema already documents each parameter's meaning. The description reinforces the SIREN-based single-company scope and the timeline semantics, but does not add significant per-parameter detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it returns a unified, chronological event timeline for a single company (by SIREN), merging multiple event sources into one decreasing flow. It also explicitly distinguishes itself from the sibling search_events, making the tool's scope 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 explicitly says to use this tool for one company at a time and directs the agent to search_events for cross-SIREN prospecting. This clear 'when to use vs. alternative' guidance fully satisfies the dimension.

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 only declare readOnlyHint/idempotentHint/destructiveHint. The description goes far beyond: the 403 upgrade_required behavior on free plan for full mode, plan-aware defaults, the ifrs block appearing only for listed companies, and the deterministic `_layout` rendering contract (order, labels, indentation, number formatting, verification checks). This is rich behavioral context fully consistent with the read-only 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 well-structured and front-loaded: mode/plan semantics come first, rendering rules second. The 8-item rendering spec is verbose (Excel number formats, non-breaking spaces) and partially redundant with the output schema's job, but it is organized, numbered, and almost all of it earns its place for an agent that must render results deterministically.

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 with 6 parameters, plan-dependent behavior, and a rendering contract, everything an agent needs is present: error behavior (403 upgrade_required), field-count expectations, output structure (_layout sections/lines), formatting conventions, and verification steps. An output schema exists, so return values need no further explanation. No meaningful gaps.

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 real value: it distinguishes compact (~40 champs) from full (~140 champs), explains plan-dependent defaults for `detail`, and illustrates the `fields` parameter with a concrete example (["roe","bfr_jours_ca","autonomie_financiere"]) plus the 130+ available field categories. It complements rather than repeats 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 opening sentence, "Historique financier detaille d'une entreprise sur plusieurs exercices," states a specific verb (get), resource (financial history), and scope (multiple fiscal years). This clearly differentiates it from siblings like get_company, get_credit_risk, and get_directors, so an agent can select it correctly without opening the 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 description gives clear, explicit context on mode selection: "Mode `fields` (recommande pour 1-5 ratios additionnels au-dessus de compact)", plan-aware defaults (compact on free, full on pro), and the explicit `detail=compact` override. It doesn't explicitly name sibling-tool alternatives or exclusions, but the mode-level usage guidance is concrete and actionable.

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, and the description adds substantial behavioral detail: merged/deduplicated content, date detection vs effective date, no pagination, truncated behavior, counts_are_partial semantics, hidden_by_plan limits, and the meaning of an empty news array. 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 well organized: purpose, trigger questions, content composition, per-line fields, filtering flags, plan limitations, and response shape. It is front-loaded and dense, though it could be slightly trimmed without losing value, so it does not reach a perfect score.

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 remarkably complete for the tool's complexity. It explains the hybrid output structure, freshness semantics, how to mark items as read via read_key, the absence of pagination, partial count warnings, plan caps, and the exact response shape. An agent has enough context to invoke this tool and interpret its 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?

Schema coverage is 100%, so the baseline is 3. The description adds practical meaning beyond the schema: unread_only is the preferred mode for daily points, truncated=true should trigger reducing since_days or filtering with event_types, and the limit context is reinforced. This goes beyond mere repetition of schema definitions.

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: the user's daily news feed of watched companies as shown on the /news page of Insourcia. It conveys the specific purpose and content composition, but it does not explicitly name sibling tools like get_events or search_events to draw a 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?

The description explicitly lists trigger questions ('quoi de neuf sur ma veille ?', 'résume-moi ma veille de la semaine') and says it should be used before writing a weekly summary. It also recommends unread_only=true for daily briefings, but it does not state when to prefer alternative tools such as get_events.

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 meaningful behavioral context beyond that: results are sorted newest-to-oldest, an empty list means no saved searches exist, result_count can be null, and alert_enabled is explained. This helps the agent interpret the response 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: a one-line purpose, a clear bulleted usage section, and a compact response definition. Every section earns its place and is scannable for an agent.

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 full parameter schema coverage and an output schema, the description covers use cases, sorting, null semantics, and empty-list meaning. No critical information an agent needs to call or interpret this tool 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 both limit and context. The description adds no extra parameter-level meaning, but none is needed because the schema carries the full burden.

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 'Liste des recherches sauvegardees de l'utilisateur', stating a specific action (list), a specific resource (saved searches), and user scope. This clearly differentiates it from siblings like create_saved_search and list_watched_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 'Utiliser cet outil' section explicitly states when to use it: before create_saved_search to avoid duplicate names, and to answer questions like 'quelles veilles ai-je ?'. It names the sibling alternative and the conditions that select this 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 declare readOnlyHint=true and idempotentHint=true, and the description adds genuinely useful behavior beyond that: a non-matching list_name returns companies: [] and total: 0 (explicitly framed as not an error), results are flattened across lists and sorted most-recent-first, and list_name must be an exact name. This is rich, non-obvious behavioral context that 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 longer than average but every section earns its place: purpose, usage scenarios, parameter semantics with edge case, and return format. It is well-structured with bullets and clear sections, though the inline response-shape explanation is slightly redundant given the output schema exists.

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?

Complexity is low (list tool with one optional filter), annotations carry the safety profile, and the description covers defaults, edge cases, sorting, and response shape — everything needed to call it correctly. Minor gaps remain, such as pagination behavior for very large result sets, but nothing material 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 description coverage is 100%, so the schema already documents both parameters; the baseline is 3. The description compensates by adding semantics beyond the schema: the default behavior when list_name is omitted (all lists returned) and the exact-match requirement including the empty-result contract. That pushes it 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+resource statement: "Liste des societes surveillees par l'utilisateur dans ses listes de veille" — listing watched companies in the user's watch lists, tied to page /lists. It distinguishes itself from siblings by contrasting with watch_company (the add operation) and unwatch_company, making the scope 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 gives explicit usage scenarios: use BEFORE watch_company to check if a company is already watched and learn exact list names, and to answer "which companies do I watch?" / "what's in my list X?". It names the sibling tool (watch_company) as the linked alternative, leaving no inference required.

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 that already-read keys are ignored and counted in already_read, that nothing is deleted and rows remain visible, that the user's last-visit date is not modified, and that the response contains marked_read, already_read, unread_remaining, and url. This fully aligns with the idempotentHint and destructiveHint 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 and front-loaded, with a clear purpose statement followed by concise bullet sections. Every sentence adds operational value: when to use, how to obtain keys, idempotence, exclusions, side effects, and response shape. No filler or redundancy.

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 with only two parameters and a fully described schema plus an output schema, the description is complete. It covers prerequisites, sequencing, constraints, side effects, and response fields, so an agent has everything needed to invoke it correctly without additional inference.

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 covers 100% of the parameters, including a detailed description for context. The description adds meaningful semantic guidance for read_keys, emphasizing that keys must be copied verbatim from get_news and that their format varies and must not be reconstructed or inferred.

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 and resource: it marks precise news signals as read on the Insourcia /news page. It also clarifies the scope by explicitly stating that targeted marking is intentional and no bulk 'mark all read' API exists, which separates it from any broader operation.

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: after presenting signals to the user and after the user confirms they have handled them. It also directs the agent to call get_news first and copy the returned read_keys verbatim, while noting that there is deliberately no mark-all endpoint.

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 it read-only and idempotent, and the description adds substantial behavioral context on top: the tool refuses to decide when uncertain, never returns a default 'best result', distinguishes lookup_failed (technical failure, to retry) from genuine no_match, and resolves instantly when an identifier is already present. No contradiction with readOnlyHint=true — this is a lookup, not a mutation.

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 densely packed with high-value information: usage conditions, sibling differentiation, status semantics, reason semantics, data-quality advice, and return-format guidance. The only redundancy is the search_companies comparison appearing twice, and the content justifies the length given the tool's nuanced refusal 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?

Very complete for a complex batch tool: covers input expectations, output shape (results[] preserving order with id passthrough, summary counts), the instruction to read summary before detailing, and per-status actions. Minor gap: no guidance on handling inputs exceeding the 200-record schema limit (batching strategy), but the output schema covers return values so the description need not repeat them.

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 beyond the schema by explaining that siren/siret/TVA inputs resolve without search, that postal_code roughly doubles the automatic match rate, and that extra tokens in the name field are costlier than truncated ones (clean city/agency suffixes). This enriches the agent's understanding of how parameter values affect outcomes.

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 operation — batch matching ('Rapprochement EN LOT') of poorly identified records to SIREN identifiers — and immediately contrasts itself with search_companies ('il rend des resultats classes, celui-ci rend une decision'). This distinguishes it from its closest sibling without requiring schema inspection.

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 states when to use this tool ('quand l'utilisateur arrive avec une LISTE de societes a identifier') and when NOT to ('Pour UNE societe cherchee par son nom, utiliser search_companies'). It also provides a downstream protocol: for review status, present candidates and let the user confirm rather than choosing. This is exemplary routing 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial non-obvious runtime behavior: include_fields is mandatory for filtered values to appear, pagination is Pro-only, _user_plan drives plan-specific limits, and unknown advanced_filters keys are rejected rather than ignored. These are exactly the behavioral details an agent needs beyond 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 the tool is complex with 40 parameters and multiple plan-dependent behaviors. It is well structured: the critical include_fields rule is front-loaded, and subsequent sections cover usage, filtering, sorting, unsupported features, pagination, and return fields. Some redundancy exists with the schema's own field descriptions, but the organization makes the information navigable for an agent.

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 this complex, the description is remarkably complete: it covers core search usage, advanced_filters, the include_fields dependency, plan-specific limits, sorting options, pagination, return fields, follow-up workflows, and known unsupported features. The presence of an output schema reduces the burden for return-value details, but the description still lists the default returned fields. Nothing essential to selecting or invoking this tool correctly appears 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 baseline is high. The description adds critical cross-parameter semantics not obvious from individual schemas, especially the include_fields mappings (dividendes_min→dividendes_verses, nb_marches_min→nb_marches_titulaire, etc.) and the rule that financial/advanced filters require include_fields. It also clarifies that SIRETs are accepted in the query field and that advanced_filters keys must be read from the schema. This meaningfully supplements the schema without replacing 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 begins with a precise statement: 'Recherche d'entreprises francaises par nom, SIREN, activite, et criteres financiers.' This names the verb, resource, and key search dimensions, distinguishing it clearly from a pure director lookup. It also explicitly routes director-focused queries away from this tool to search_director_companies, further clarifying its 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?

The description provides explicit when-to-use guidance: use this tool when a user looks up a company by name or explores a sector. It also gives a concrete workflow ('trouver le SIREN, puis utiliser get_company ou get_financials'), names the alternative for direct director searches, and advises proposing create_saved_search for recurring needs. This is strong, actionable routing that leaves little 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 carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), lowering the bar. The description adds genuinely useful behavioral context: coverage limited to direct mandates (excludes resolved_from_pm), and the disclosure that an empty result means no direct mandate exists for that exact identity, prompting the agent to verify date_naissance. No annotation contradiction.

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 (~220 words) but front-loaded with the core purpose and organized into clear sections: purpose, tool-family positioning, required parameters, response shape, and scope note. Each paragraph earns its place; the homonym disambiguation point is restated a couple of times and could be tightened, but the structure remains highly scannable.

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 (covering return values) and annotations cover the safety profile, the description covers everything else an agent needs: required parameters, how to obtain them, empty-result semantics, scope boundaries, and pointers to all three relevant sibling tools. Rate limits and auth requirements are the only omissions, which are minor for an idempotent, read-only search 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 100%, so the schema already documents every parameter, giving a baseline of 3. The description adds value beyond it by flagging that all parameters are required, reinforcing the YYYY-MM-DD format, and providing the workflow to obtain date_naissance beforehand via search_directors or get_directors.

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: maps the corporate footprint of ONE physical person via all companies where they hold a direct mandate, disambiguated by exact date of birth. It also positions itself as the 'person -> entreprises' pivot and explicitly names sibling tools (search_directors, get_directors) it complements, so an agent can distinguish it without opening any 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?

Gives explicit when-to-use guidance (M&A perimeter tracing for a founder/director across holdings, SCIs, subsidiaries) and explicit when-not-to-use guidance: search_companies for broader filtering that includes resolved_from_pm mandates with month granularity, and get_company for capitalistic holding structure. No ambiguity remains about tool 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?

Annotations already declare readOnlyHint true and destructiveHint false, and the description adds substantial behavioral context: active mandates are returned by default, include_inactive toggles old mandates, and there is an important disambiguation warning about same-name/different-person cases. It also describes the pagination and response structure. 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 front-loaded with the core purpose, then organized into parameter semantics, response shape, disambiguation notes, and sibling tool routing. Every section carries operational value; nothing feels redundant or decorative.

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 complexity of disambiguating homonyms and the availability of an output schema, the description is complete: it defines the output structure, explains defaults, warns about identity pitfalls, and gives explicit chaining paths to related tools. There is no missing information that would prevent an agent from using 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 meaning beyond the schema: prenom is described as a disambiguator, role gets example values, and include_inactive's effect on active mandates is explained. It does not deeply expand on limit or context, but the schema already covers them.

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 and resource: searching for people/directors across all French companies by last name. It explicitly contrasts with search_companies, which returns companies, so the agent can distinguish the tool from siblings without ambiguity. The use case is concrete.

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 when-to-use guidance: when you need people rather than companies, e.g. 'all companies where a director named DUPONT sits'. It also identifies when to switch to search_director_companies or get_directors, providing a clear routing rule based on the data already known.

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 convey read-only, idempotent, non-destructive, open-world behavior. The description adds useful behavioral context: event-level results, coverage of BODACC and silver scalar sources, and the mandatory-filter condition. 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 front-loaded with the core purpose, then presents the coverage, the critical filter rule, and compact examples. Every sentence earns its place for a tool with 15 parameters.

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 complex search tool with 15 parameters and rich schema/annotations, the description covers output shape, event type coverage, data sources, the mandatory-filter rule, and representative use cases. The output schema handles return-value details, so 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 baseline is 3. The description adds value by mapping natural-language use cases to specific parameters (e.g., 'Cessions de fonds > 1M en Ile-de-France depuis 2024' -> type, region, date_min, prix_min) and clarifying filter semantics across event types.

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 a specific verb and resource: a unified cross-SIREN search that returns individual events (not companies), and enumerates the eight event types. It does not explicitly differentiate from the sibling get_events, so it falls short of a 5.

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 an explicit filter requirement rule (region/department/NAF or event filter, else 400) and three concrete query-to-parameter examples. It does not name alternatives or state when not to use this tool, 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, the description discloses nuanced behavior: default removal from all lists, idempotent false-result behavior, list preservation even when emptied, alerts remaining active, and successful removal of companies absent from the index. This is substantial operational context that an agent could not infer from annotations or schema alone.

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 front-loaded purpose sentence, a usage trigger section, and bullet-pointed behavioral details. It is somewhat long and repeats the response shape that an output schema already provides, but every section earns its place by clarifying edge cases and side effects.

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 core operation, default vs. scoped behavior, idempotency, side effects on lists and alerts, edge cases around missing companies, and a fallback verification tool. Combined with the rich annotations and output schema, the 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?

The input schema already has 100% parameter coverage and describes siren, context, and list_name including the omission default. The description reinforces list_name behavior but does not add meaning beyond the schema; it mostly restates the same semantics in prose.

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: 'Retrait d'une societe de la surveillance' and explains it removes a company from the user's watchlist. It also positions itself as the inverse of watch_company, making the tool's purpose unambiguous and clearly distinct from its sibling.

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 ARRETER de suivre une societe') and gives concrete user-phrase triggers. It also directs the agent to call list_watched_companies before mass removal or when a list name is uncertain, which is valuable routing 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 (idempotentHint: true), the description adds concrete behavioral details: list auto-creation, idempotent already_watched=true behavior, daily alert semantics with future events only and no history replay, and the response fields. It also clarifies that the user should be given the resulting URL. This is rich and non-contradictory.

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 guidance, followed by a compact 'Fonctionnement' bullet list covering the essential behaviors and the response shape. Every sentence carries operational value, including the closing instruction to communicate the URL to the user. It is thorough without being 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?

The description fully equips an agent to invoke the tool correctly: clear selection criteria, parameter semantics, idempotency behavior, alert semantics, response format, and post-call instruction. With 100% schema coverage and an output schema present, nothing required for correct usage 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 covers 100% of parameters, so the baseline is 3. The description adds extra meaning for list_name (default list 'Surveillance', auto-created) and enable_alert (daily frequency, future events only, no replay), going beyond the schema descriptions. Siren and context parameters gain nothing additional, but the overall semantic enrichment justifies a 4.

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 : l'ajoute a une liste de veille de l'utilisateur'. It clearly differentiates this tool from simple lookup by naming get_company as the alternative for mere 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: when the user wants to SUIVRE a company over time (acquisition target, competitor, client, risky supplier), and when not to use it: for simple consultation, with the explicit alternative 'utiliser get_company'. This gives an agent unambiguous selection criteria.

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