Pillr

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the bar is low, yet the description adds substantial method disclosure: 2,000-inhabitant and 10-sales thresholds, DVF source for price rankings, a 30-commune cap plus total-count reporting, and the 'Aucun score Pillr' caveat. These are exactly the traits an agent needs to interpret results without over-claiming.

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?

Purpose and criteria come first, then methodology, then the alternative-tool routing and exclusions – well front-loaded with no filler sentences. It is dense with numbers in the middle, which costs a little readability but every clause carries information.

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 output schema, the description still conveys return shape (at most 30 ranked communes plus the total number ranked) and the data basis. Combined with the exclusion list, an agent has enough to call it correctly and describe its output honestly.

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

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

Schema coverage is 100% and the schema already spells out each enum value and its sort direction, so the description's restatement of the three criteria adds little beyond it. The depiction thresholds (population, sales) inform result interpretation but not the parameters themselves, so 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?

Opens with a specific verb and resource ('Classe les communes d'UN département selon un critère public') and immediately scopes it to a single department and a named criterion set. The capitalised 'UN' plus the ranked-list framing make it unmistakably distinct from per-commune siblings like prix_m2_commune or marche_commune.

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 concrete when-to-use examples ('où investir en Gironde', 'les communes les moins chères du Nord'), names the explicit alternative for the opposite case (comparaison_communes for already-named communes), and states exclusions (Paris, Bouches-du-Rhône, Rhône are not ranked). Nothing is left to inference about when to pick 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 read-only, idempotent, non-destructive, closed-world behavior. The description adds meaningful context beyond those annotations: price provenance is included and no Pillr score is returned, which sets expectations about what the agent will and will not get back.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the comparison scope and then moves cleanly to usage and alternatives. The first sentence is long because it enumerates all indicators, but each item is relevant to tool selection; only that density keeps it from being 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?

For a read-only tool with rich annotations, one fully documented parameter, and no output schema, the description is nearly complete: it lists returned indicators, provenance, and the absence of a proprietary score. It does not describe response structure or missing-data behavior, which is a minor remaining gap.

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 100% schema description coverage, the schema already documents the accepted commune formats, INSEE codes, arrondissement syntax, postal-code fallback, and the 2–5 item bounds. The description only reaffirms the 2–5 range and cross-references the commune parameter of other tools, adding modest value over 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?

States a specific verb and resource — comparing 2 to 5 French communes — and enumerates the exact indicators compared. It explicitly distinguishes itself from marche_commune and classement_departement, so an agent can route correctly without opening schemas.

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

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

Gives an explicit trigger: use whenever a question puts several communes in balance, with a concrete example. It also names the alternatives for single-commune detail and unnamed-commune discovery, covering when not to use it.

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/non-destructive annotations it adds real behavioral context: every conclusion carries its rule and source, the rule base is date-stamped, and missing facts are returned as questions rather than assumed. It also discloses a critical scope limit (no PLU or servitude lookups; terrain protections must be supplied as parameters) and that output is general information, not legal advice or a municipal decision.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the deliverable list, then scope limits, then the market-data disclaimer and legal caveat. The long opening sentence is dense but every clause names a distinct output; no sentence is filler, though the run-on structure makes the first read heavier than 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 34-parameter rule engine with no output schema, the description covers scope, the question-back behavior, source attribution, and explicit exclusions. What remains implicit is how the conditional parameters cluster by type_travaux, which an agent must still infer from the schema.

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% across all 34 parameters with enums and units documented, so the schema does the heavy lifting and the baseline applies. The description adds only one semantic hint — that terrain protections must be declared via parameters — and otherwise does not explain the interaction between the single required type_travaux and the 33 conditional, often optional inputs.

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 concrete deliverable set with specific nouns: which urbanism formality applies (none, prior declaration, building/development/demolition permit), which Cerfa form, whether an architect is mandatory, which documents, and the instruction deadline. An agent can distinguish this from all six sibling tools, which are price/rent/market tools, 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?

It explicitly bounds scope ('ce connecteur ne lit ni le PLU ni les servitudes') and routes away from itself for market data ('pour les prix et les loyers, les autres outils'), which is exactly the sibling set. It does not enumerate a hard when-not-to-use case beyond that, so it stops short of a full routing rule set.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes beyond them by disclosing what the returned figure actually is (modeled advertised rent, not observed rent or a legal cap, with rent control explicitly out of scope) and what the response contains (hors charges, 95% interval, €/m², ANIL/DHUP segment). It doesn't cover freshness or data-source vintage, which keeps it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then usage examples, then the sibling alternative, then the caveat — a sound ordering with no filler. The first sentence is long and packs several output elements, which slightly taxes scanning, but no sentence is expendable.

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 output schema, the description carries the return-value burden itself and does so (rent, interval, €/m², segment, optional yield), while also warning what the number is not. Nothing an agent needs to call this correctly on 4 simple parameters 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 baseline is 3, but the description adds meaning the schema lacks: prix_achat is optional and only feeds the gross yield, and surface is optional with an example-surface fallback reflected in the answer. That connects the parameters to observable output behavior rather than restating the fields.

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 ("Loyer mensuel estimé d'UN logement") plus the exact inputs that define it (commune, typologie, surface), and explicitly contrasts with the sibling marche_commune. An agent can tell it apart from prix_m2_commune and marche_commune 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?

Gives concrete invocation examples ("combien louer un T2 de 40 m² à Nantes", "quel rendement pour ce T3 à 180 000 €") and names the alternative: "Pour le loyer médian et le rendement de marché de la commune entière, utiliser marche_commune". Both the when and the when-not are explicit.

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

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

Although annotations already declare readOnly, idempotent, non-destructive and non-open-world behavior, the description adds important context: no individual listings are returned, data older than 45 days is not served, update months return only limited fields, and the Pillr score/full analysis are excluded. 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?

Purpose and included metrics are front-loaded, followed by alternatives and exclusions in a logical order. The text is very dense and one long semicolon-heavy paragraph, so it is informative but could be more 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?

There is no output schema, so the description carries the return-value burden, and it does: it enumerates the market metrics, aggregation source, freshness limits, omission of individual listings, and excluded Pillr score. This is complete enough for an agent to invoke a complex read-only market 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 description coverage is 100% and the commune parameter already documents name, INSEE code, arrondissement notation, and postal-code fallback. The description adds only the 'UNE commune' scope and aggregation note, so the 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?

States a specific resource and scope: a complete market synthesis for ONE commune, explicitly for judging whether to buy or invest. It enumerates the included metrics and distinguishes itself from siblings, so an agent can identify it 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?

Explicitly routes the agent to alternatives: prix_m2_commune for price alone, loyer_logement for a precise rent, and comparaison_communes for comparing communes. It also states the 45-day freshness cutoff and the collection-update-month caveat.

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, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context: the provenance distinction (measured on DVF sales vs estimated), the arrondissement counting for Paris/Lyon/Marseille, and the rule that missing prices are reported as absent, never guessed. It does not restate annotation fields.

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 core scope is front-loaded in the first clause, followed by routing rules. It is dense but each sentence carries information; the only slight excess is the closing reassurance sentence, which is borderline redundant with the earlier 'jamais deviné' clause.

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?

No output schema exists, so the description deliberately names the return fields (valeur, provenance, millésime, date de reconstruction) and the missing-value behavior. Combined with the explicit routing among siblings, 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 description coverage is 100% and the schema already documents the commune/INSEE/postal-code forms and the PLM arrondissement notation. The description adds essentially nothing about the parameter beyond that, 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?

States a precise verb+resource+scope: reference price per m² for ONE French commune, apartments and houses, explicitly 'et rien d'autre'. It also enumerates the returned facets (valeur, provenance, millésime), so the agent knows exactly what this returns versus the sibling 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?

Gives an explicit inclusion rule ('quand la question porte seulement sur le prix d'une commune') and names each alternative with the condition that selects it: marche_commune for rent/yield/trend/tension, prix_m2_quartiers for neighborhood detail, comparaison_communes for multiple communes.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses result ordering (du plus cher au moins cher), the publication threshold (quartiers d'au moins 5 ventes), the cap (40 max per property type), and the meaning of the provenance field. It effectively documents the return payload in the absence of an 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?

Front-loads scope and granularity, then the exclusion rule and alternative. Dense and largely waste-free, though the long run-on first sentence mixing returned fields, thresholds and caps could be split for faster scanning.

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 tool with no output schema, the description covers what is returned (prix, nombre de ventes DVF, provenance, part), how it is ordered, what is suppressed, and how it differs from siblings. An agent has everything needed to invoke it correctly and interpret the result.

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%, with the commune parameter already explaining name/INSEE/arrondissement forms and the type_bien enum documented. The description reinforces the single-commune constraint but adds no parameter syntax or format detail beyond what the schema already provides, so the baseline 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?

States a specific resource (prix au m² des appartements et maisons), a specific granularity (quartier par quartier, IRIS de l'INSEE) and a specific scope (UNE commune), then explicitly rules out the sibling prix_m2_commune. An agent can distinguish it from prix_m2_commune, marche_commune and comparaison_communes 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 a concrete use-case («quel quartier est le moins cher à Lille»), a secondary use (situer un quartier dans sa commune), the explicit alternative for the commune-level question, and the negative condition (communes not split by INSEE into quartiers have no quartier price). It even routes Paris/Lyon/Marseille queries to arrondissement naming rather than a different tool.

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