Partner Construction

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is known; the description adds real value by stating it returns phone numbers and links and creates no request — the agent knows to hand the contact info to the user rather than expect a submission. It does not describe exactly how many advisors or what the link payload looks like, but that is minor for an info-only tool.

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?

Two tight sentences: the first states what the tool provides, the second pre-empts the most likely misinterpretation (that it submits a request). Front-loaded and waste-free.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters, no output schema and full annotation coverage, the description supplies everything the agent needs: what is returned (phone, links), that no state changes, and that the user completes the request themselves. 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?

The tool takes zero parameters, so per the baseline a 4 applies. There is nothing for the description to disambiguate on the input side.

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

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

Names the concrete resource (un conseiller Partner Construction, a BTP décennale broker) and the concrete action (obtenir téléphone + liens, ou demander un devis). It also states the negative scope up front — 'Ne crée AUCUNE demande' — which cleanly separates it from creer_ma_demande.

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 use case is clear: an artisan who wants to reach an advisor or get a quote routes here. The explicit exclusion ('ne crée AUCUNE demande … l'artisan fait sa demande lui-même') tells the agent when not to use it, though the sibling creer_ma_demande is not named directly, leaving the cross-reference implicit.

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

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

Annotations only flag write/destructive/idempotent; the description adds what those mean in practice: a record is created at the broker, a proposal may be emailed on the artisan's behalf, the call is refused without consent so nothing is sent, no data may be invented, and `aDireAuVisiteur` must be echoed verbatim to the visitor. It also discloses replay semantics (same inputs plus same numero_demande → no duplicate), which is exactly the operational meaning of idempotentHint.

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?

Length is substantial but front-loaded with the write marker, purpose, and the hard prerequisite before the numbered procedure. The verbatim consent scripts consume real space but are compliance-critical and cannot be paraphrased; minor redundancy exists between the step-3 wording and the preceding step-2 quote.

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 17-parameter, destructive, consent-gated write with no output schema, the description still supplies everything needed to call it correctly: prerequisite ordering, per-situation required fields, the exact consent gate, and the required handling of the `aDireAuVisiteur` return field. Remaining gaps are peripheral optional fields, not call-blocking ones.

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?

With 41% schema coverage across 17 parameters, the description compensates for the most consequential ones: accord and texte_accord (exact wording gate), numero_demande (dedup key), situation_assurance (must match the estimate call), email's conditional requirement, and the cotisation / mois_echeance pairing for in-force contracts. It says nothing about ville, prenom, code_postal, raison_sociale, chiffre_affaires, metier, or precisions, so roughly half the surface is still undocumented.

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 — it transmits an artisan's décennale insurance request to the broker Partner Construction so an advisor can issue a proposal and call back — and explicitly distinguishes itself from the sibling estimate tool. The 'ÉCRITURE' prefix immediately separates it from read-side siblings like estimer_tarif_decennale and lire_fiche_metier.

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 an explicit ordering constraint ('à n'appeler QU'APRÈS estimer_tarif_decennale'), an explicit no-go condition (no explicit 'oui' → the tool refuses and sends nothing), and conditional data requirements (email mandatory for an in-force contract, optional otherwise). Alternatives and exclusions are both named, leaving nothing to inference.

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

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

Beyond the read-only annotation, the description discloses crucial behavioral traits: the estimate is only a starting price, must never be presented as a firm offer, must not invent figures or dates, and `aDireAuVisiteur` plus `suite.lien` must be rendered as-is. It also explains the multi-turn flow via the `questionSuivante` field, which is exactly the context an agent needs.

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 purpose, then uses a numbered question order and explicit warnings. Despite being dense, every sentence carries operational or safety-relevant information for a multi-turn estimation tool.

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 absence of an output schema, the description still names the key output fields (`questionSuivante`, `aDireAuVisiteur`, `suite.lien`) and explains how to use them. It also covers the required question sequence and safety constraints, making the definition complete for an agent to invoke 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 already 100%, so parameter formats and enums are well documented. The description adds procedural meaning by specifying which parameters to ask for first, which are conditional on an ongoing contract, and that current premium should be omitted rather than estimated.

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 very specific action: estimating the annual/monthly starting price of décennale insurance for French BTP artisans and companies, compared with their current payment. The audience, geography, provider, and comparative scope make the tool clearly distinct from siblings such as creating a request, contacting an adviser, or searching content.

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 a clear mandatory first question (`situation_assurance`) and a conditional sequence for the remaining questions, which is strong operational guidance. It does not explicitly say when to prefer or avoid sibling tools such as `contacter_un_conseiller` or `creer_ma_demande`, so it lacks full alternative routing.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description still adds value by enumerating what comes back (l'essentiel, points clés, texte, FAQ, URL, date) in Markdown, which matters because there is no output 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?

One compact sentence that front-loads the action and return value, then tacks on the slug provenance. No filler, though the parameter hint is buried at the end rather than surfaced prominently.

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 single-parameter read tool with no output schema, the description covers purpose, output shape, and how to obtain the input. The main remaining gap is failure behavior for an unknown slug, which is minor.

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

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

Schema description coverage is 0% and the single 'slug' parameter has no schema description, so the description carries the burden. It explains the slug's provenance ("vient de rechercher"), which is the key operational detail an agent needs; format specifics are still absent.

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 ("Renvoie un article publié de Partner Construction") plus the output format (Markdown) and the sections returned. It is distinguishable from lire_fiche_metier by the resource type, though that sibling is never named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The closing clause "Le slug vient de rechercher" implicitly tells the agent this tool must be preceded by the search tool, which is useful workflow context. However, there is no explicit when-to-use/when-not guidance and no contrast with lire_fiche_metier.

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, non-destructive and closed-world, so safety is covered. The description adds valuable behaviour beyond that: only the *published* fiche is returned, and it enumerates the payload sections. It doesn't say what happens for an unknown or unpublished slug (error vs empty), which is the remaining gap.

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?

Two sentences, zero filler: the first front-loads what is returned and its sections, the second gives the only non-obvious calling constraint. Every clause 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?

There is no output schema, but the description enumerates the returned content (coverage, exclusions, sinistre examples, risks, FAQ, URL), which substitutes for it. Combined with the single documented parameter and the annotations, an agent has everything needed 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 0% (slug is type-only), so the description must carry the burden — and it does: it explains the slug's origin ('vient de rechercher, type « metiers »') and gives example values (plombier, électricien, maçon). Format details (accent/case handling, exact slug syntax) are still unstated.

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?

Specific verb+resource ('Renvoie la fiche publiée d'un métier du BTP') with a concrete inventory of what the fiche contains (couverture/exclusions décennale, sinistres, risques, FAQ, URL). This clearly separates it from lire_article (articles) and rechercher (slug discovery).

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 the prerequisite explicitly: the slug must come from 'rechercher (type « metiers »)', which routes the agent to the correct upstream sibling. It stops short of naming exclusions or alternatives (e.g. when to prefer lire_article), so it's clear context but not full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds useful context about the content universe and the returned fields (titre, URL, résumé, date), though it does not discuss pagination or result limits 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 front-loaded with the core verb and scope, then adds a useful next-step sentence. It is dense but every sentence serves a purpose, 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 search tool with no output schema, the description covers the content universe, return fields, and follow-up actions well. The main gap is that it omits behavior for the 'type' and 'limite' parameters, which matters given the low schema coverage.

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 only 33%: only 'requete' has a schema description. The description does not explain the 'type' filter or the 'limite' parameter at all, so it does not compensate for the undocumented parameters. It implies that articles and fiches métier exist, but does not connect this to the 'type' enum.

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 ('Cherche') and clearly identifies the resource: published Partner Construction content, split into articles and fiches métier. It also distinguishes this tool from the sibling read tools by directing the agent to lire_article or lire_fiche_metier for full content.

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 names the alternatives (lire_article, lire_fiche_metier) and states the condition for using them: when the full content is needed. The search-first/read-later workflow is clear without inference.

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