Fonciq — Zones inondables et Registre foncier du Québec (Québec flood zones & land registry)

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

Goes well beyond the annotations: discloses the POST route, the registre:write scope, that idempotency_key is sent as the Idempotency-Key header with 24 h retention and stored-answer replay on retry, required Bearer API key, and precise billing (0,99 $ per delivered document on live keys; test keys and 4xx/5xx free). The fail-closed behavior on a missing deed is exactly the kind of trait an agent needs and no annotation conveys.

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

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

Every sentence carries real information (billing, auth, idempotency, fail-closed), but the full French restatement roughly doubles the length without adding facts, and leading with the raw route 'POST /v1/actes' is a weak front-load for an agent selecting a 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?

For a billed, authenticated, idempotent document-retrieval tool with no output schema, the description covers auth requirements, cost model, retry semantics, failure mode and availability limits. An agent has everything needed to call it correctly and predict charges.

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 earns a bump by explaining the runtime meaning of idempotency_key (transmitted as the Idempotency-Key header, retained 24 h, retry returns the stored answer), which the schema's 'unique key for this write' does not. Nothing is added about registration_number or circonscription formatting 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?

States a specific verb and resource: returns the PDF of one deed identified by registration number and circonscription foncière. It is distinguishable from document_get and plan_get by naming the deed artifact explicitly, though it never names those siblings to contrast with them.

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 clear usage context: works when Fonciq holds the deed (no Registre fee), fails closed when the deed is missing, and notes that the structured deed analysis is 'Bientôt' and not offered here — effectively a when-not-to-use clause. It does not point at any sibling tool as the alternative for a missing deed or for other document types.

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?

It adds substantial behavior beyond the annotations: required batches:write scope, Bearer API key auth, Idempotency-Key handling with 24-hour stored answers, and detailed billing rules including test-key and 4xx/5xx zero-cost behavior. It also distinguishes Fonciq billing from the Registre's separate 1,50 $ fee, which is useful operational context not captured by 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 purpose is front-loaded in the first sentence, but the description is heavily bloated by full bilingual duplication and repeated billing/auth statements. Several sentences repeat the same information in English and French, so much of the text does not earn 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 mutation tool with rich annotations and no output schema, it covers auth, scope, idempotency, limits, account routing, and billing thoroughly. It does not describe the return value or queued-job identifier, which would help an agent understand what comes back from a batch submission.

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

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

Schema coverage is 100%, so the schema already documents all three parameters; the baseline would be 3. The description adds real meaning beyond the schema by explaining idempotency_key is sent as the Idempotency-Key header, retained 24 hours, and reused on retry, plus that account spreading is overridden when an account is pinned.

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: "Queues an index for up to 500 lots" via POST /v1/batches, with the scope clarified as active Registre accounts unless one is pinned. It is clear what the tool does, though it does not explicitly name a sibling such as registre_index_request to sharpen batch-vs-single differentiation.

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 implies batch usage through "up to 500 lots" and account spreading, so an agent can infer it is for many lots at once. However, it gives no explicit when-to-use/when-not guidance and does not name registre_index_request as the single-lot alternative.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds materially beyond them: billing reads cost 0, an API key is required (Authorization: Bearer), the billing:read scope, and the data provenance (Fonciq's own pull log rather than a portal statement). It stops short of describing response shape, which leaves a small 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?

The core statement is front-loaded and useful, but the text is fully duplicated in French, and the cost paragraph is repeated verbatim in both languages ("Billing reads cost 0" / "Les lectures de facturation coûtent 0"). Roughly half the characters carry no new 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?

For a read-only, no-required-param tool with 100% schema coverage and no output schema, the description supplies the scope, auth requirement, cost, data source and an explicit negative disambiguation. The only unstated element is what the response entries look like, which matters less without an output 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 coverage is 100%, so `from`, `to` and `rf_account_id` are already documented with formats and the omit-for-default behavior. The description only restates the per-account/per-period framing and adds no format or edge-case 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?

States a specific endpoint and resource: estimated Registre foncier fees per connected account for a period, and explicitly excludes the nearest misinterpretation ("Not Fonciq platform billing"), which differentiates it from the sibling billing_usage. An agent can identify the tool 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 clear context for use — internal Fonciq pull log, no portal statement is read, per-account and per-period scope — plus the required scope (billing:read). It never names an alternative sibling or states when-not to use it, so the routing signal is implied rather than 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?

Annotations already cover read-only/idempotent/non-destructive, and the description adds genuinely new operational context: pagination, required scope billing:read, zero cost per read, and the need for the caller's own API key via Bearer auth. That is useful pre-call information an agent cannot get from 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 operational facts are front-loaded (endpoint, purpose, scope, cost, auth), which is good. However the description is fully duplicated in French, roughly doubling length without adding information an agent needs, and the leading endpoint string largely restates the tool's own path.

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 and 5 optional parameters, the description should say more about what a 'line' actually contains and what happens with omitted from/to. 'One line per pull' is suggestive but leaves the return shape and defaults underspecified for a billing tool an agent must call 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 80%, so the schema already documents to/from/cursor/rf_account_id; the description adds nothing about any parameter. Notably 'limit' has no schema description and the description does not compensate, nor does it explain default date-range behavior when from/to are omitted (all params optional). 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 the endpoint (GET /v1/billing/usage) and describes the resource concretely: 'the documents behind GET /v1/billing, one line per pull, paginated.' This implicitly separates it from the sibling billing_get (summary) by framing this as the per-line breakdown. Not a crisp verb+resource phrasing, but an agent can tell the two billing tools apart.

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?

Usage is only implied: you call this to enumerate per-pull fee lines behind the billing summary. It never explicitly says 'use billing_get for totals, use billing_usage for line items' nor names any exclusion. The 'billing reads cost 0' note is a mild incentive to call it, but not real when-to-use 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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful context beyond them: the required jobs:read scope, mandatory Bearer API key in the Authorization header, and explicit zero-cost billing behavior — all things an agent cannot infer from the schema or 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 route and purpose are front-loaded, which is good, but every sentence is duplicated in French, roughly doubling the length with no new information for an English-reading agent. 'Billing: identical to the HTTP route' followed by 'is not billed (0 $)' is also redundant restatement.

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 rich annotations and no output schema, the definition covers auth, scope, cost, and the nature of the returned data ('parsed lines'). It stops short of describing entry structure, ordering, or pagination, but nothing critical to invoking 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?

Only one parameter exists and schema coverage is 100% ('Document id.'), so the schema already does the work. The description implies via the route that the id identifies the index document, but adds no format, source, or disambiguation details beyond that implication.

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 the concrete operation and resource: 'Stored parsed lines of one index document', reinforced by the HTTP route GET /v1/documents/{id}/entries. An agent can tell this returns entry lines rather than document metadata (document_get) or job output (job_results), though the description never explicitly contrasts itself with those siblings.

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?

There is no statement of when to call this versus alternatives such as document_get, registre_index_request, or job_results. The only contextual hints are the jobs:read scope and the 'not billed' note, which are operational facts rather than selection 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 (readOnly, idempotent, non-destructive), the description discloses the required scope (jobs:read), the auth requirement (own Fonciq API key as Bearer fq_live_…/fq_test_…), and that the call produces no new document and is not billed. That is exactly the kind of operational context annotations cannot carry.

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 essential information is front-loaded in the first two sentences, but every sentence is then repeated verbatim in French, roughly doubling length without adding meaning for an agent. The billing statement is also duplicated within the English half ('identical to the HTTP route' plus 'not billed (0 $)').

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 annotations covering safety and no output schema, the description supplies return format (embedded base64 PDF), auth, scope, and billing — enough to call it correctly. It stops short of linking to prerequisite tools or clarifying the index-vs-deed distinction against acte_get.

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 a single documented 'id' parameter, so the schema already does the work. The description adds no format, source, or constraints for the id (e.g., where to obtain it), so 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?

The first sentence names a specific verb (GET/download) and resource (PDF of an index or a deed for your organization) and states the return encoding (embedded application/pdf, base64). Sibling differentiation is only implicit — acte_get and plan_get are never named, so an agent must infer that 'deed' here overlaps with acte_get.

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?

Usage is implied through the resource description ('PDF of an index or a deed produced for your organization'), so the agent can infer this is the retrieval step after an index/acte exists. But there is no explicit when-to-use versus when-not, and no mention of what to call first (e.g., document_entries) or how this differs from acte_get.

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/non-openWorld, and the description adds substantial context beyond them: rate limits (30/min, 1000/day per IP shared with the HTTP endpoint), per-source CC BY 4.0 attribution, a disclaimer, the historical status of the 2017-2019 ZIS, and the March 1, 2026 new-generation map gap. This is exactly the extra context annotations cannot carry.

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 English text is well front-loaded ("FREE, no API key") and every English sentence carries caveats that matter. However, the full French translation roughly doubles the length without adding information an agent can act on, which is padding in a single tool description.

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

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

Despite having no output schema, the description enumerates the return payload (zones at the point, source zone type, distance to nearest zone, attribution, disclaimer) and flags the limits and data vintage. Nothing an agent needs to call this correctly or interpret the result is missing.

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

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

With 100% schema coverage the baseline is 3; the description earns more by stating the mutual-exclusivity constraint (exactly one of lat+lon, address, lot) that the schema, which has zero required params and no oneOf, cannot express, and by noting address is matched to the Référentiel québécois des adresses and lot to RQA address points. Only lang is left solely to 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 ("Checks which of 9 open Québec flood-zone sources ... intersect a point") and enumerates the sources by name. It is unmistakably distinct from every sibling (lot_get, lot_resolve, plan_get), none of which deal with intersect queries.

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 input contract ("Give exactly one of: lat+lon, address ... or lot") plus clear when-not-to-trust guidance: a no-hit never means the property is outside a flood zone, the lot boundary is not evaluated, and answers must be confirmed on the official Québec map because new-generation maps are excluded.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description still adds genuinely new context: the jobs:read scope, the requirement to supply your own Fonciq API key as a Bearer token, and the fact that the call returns no new document and is billed at $0. That is real value beyond structured 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 opening is well front-loaded with the route and returned fields, but the entire payload is then duplicated in French — including the billing and auth sentences verbatim in meaning. Roughly half the text is redundant, which dilutes rather than reinforces the signal.

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 does the work of naming the return payload (status, documents, result.index/indexes, daily capacity), and it covers auth, scope, and cost. What is missing is lifecycle context — terminal vs. in-progress statuses and whether to poll — which matters for a job-status tool.

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

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

Schema coverage is 100% and the single parameter 'id' is documented in the schema, so the schema carries the load. The description only implies the id via the route template and adds no format, source, or provenance detail (e.g., where a job id comes from, such as batch_submit). 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 verb and resource ('GET /v1/jobs/{id}') and enumerates what comes back: status, documents, result (result.index or result.indexes), and per-account daily index capacity. That is far more than a restatement of the name. It stops short of 5 because it never distinguishes itself from the sibling job_results, which plausibly returns overlapping result data.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no mention of alternatives. The presence of job_results as a sibling makes this omission material — an agent cannot tell from the description which of the two to call for result data, nor whether polling this endpoint is the intended pattern.

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, so the bar is lower. The description still adds real value: billing is 0 $ because no new document is delivered, and a personal Fonciq API key must be supplied in the Authorization header. That is context the annotations do not carry.

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 English statement is front-loaded and efficient, but every sentence is duplicated in French with no added information, roughly doubling the length. That duplication is redundancy rather than concision, keeping it at 3.

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 burden of shape, and it does state JSON with one block per lot and that no new document is produced. Billing and auth are covered. Slightly more detail on the block structure would close the 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?

Schema description coverage is 100% with a single 'id' parameter, so the schema already does the work. The description only reinforces that the input is a job id implicitly through the route text, adding nothing like format or validity constraints beyond the schema. 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?

The description gives a specific endpoint and resource: 'GET /v1/jobs/{id}/results. Parsed index lines of a finished job (JSON, one block per lot).' An agent can distinguish it from job_get or document_get by the returned content (parsed lines per lot). It doesn't explicitly name which sibling to use instead, so it stops 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?

'Of a finished job' implies the prerequisite (job must be complete), and 'The index PDF remains the source of record' hints at the trade-off, but there is no explicit statement of when to prefer this over job_get, lot_get, or document_entries. Usage is implied rather than stated.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantive context beyond them: required scope lots:read, own Fonciq API key in the Authorization header with token prefix format, billing identical to the HTTP route, and explicitly 0 $ / not billed. That is exactly the auth and cost information an agent needs before calling.

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

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

Front-loaded with the route and payload contents, which is good, but the full bilingual duplication roughly doubles the length and the billing point is restated redundantly ("identical to the HTTP route" and "0 $" in both languages). Every element is accurate but not maximally compressed.

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 what is returned, what is not performed, required scope, authentication mechanism, and cost. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single `lot` parameter is documented as "Lot number." The description's `{lot}` path template adds only positional context, no format or validation guidance. Baseline 3 is appropriate since the schema carries the semantics.

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 ("Stored profile of a Québec lot") plus the exact HTTP route, then enumerates the contents (cadastre, assessment-roll value in cents, stored index lines). The negative clause "Does not pull a new index" separates it from the index-request sibling, so an agent can pick 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 a clear use context — retrieve an already-stored profile — and an explicit exclusion ("does not pull a new index", "returns no new document"). It implies the alternative (registre_index_request) without naming it, so routing is inferable but not spelled out.

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/closed-world, so the bar is lower, and the description still adds real context beyond them: the required scope (lots:read), the need for the caller's own Fonciq API key in the Authorization header, and the billing outcome ('returns no new document and is not billed (0 $)'). The only missing behavioral detail is what the response payload looks like when zero or multiple lots match.

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 English/first sentence is well front-loaded with the route and the core resolution semantics. However, the text is fully bilingual and duplicates every operational fact twice (billing, API key, 'not billed (0 $)' appear in both languages), so a meaningful share of the payload restates rather than adds 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?

For a read-only, two-parameter lookup with no output schema, the description covers source, scope, auth, and cost, and it names the resolution outputs (lot number(s), cadastre, matricule). It falls short only on the mutually-exclusive-or-not question and on what happens when no lot matches, which an agent needs before calling.

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 both parameters are already documented in the schema, and the description only restates them as 'Give address or matricule'. It adds no semantics the schema lacks — no format examples for the matricule, no statement of whether address and matricule are mutually exclusive or may be combined. 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?

The description states a specific verb+resource ('Resolves a Québec address or a property-assessment matricule to lot number(s), cadastre and matricule') and even names the backing route GET /v1/lots/resolve. That is far clearer than a tautology, but it never explicitly distinguishes itself from the sibling lot_get (retrieve a lot once you already have its number), leaving the resolve-vs-fetch boundary to inference.

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 instruction 'Give address or matricule' implies usage, and the source data ('from the municipal assessment rolls') hints at context, but there is no explicit when-to-use, no when-not, and no named alternative such as lot_get. Critically, both parameters are optional in the schema, yet the description never says what happens if neither, or both, are supplied — an ambiguity an agent will hit immediately.

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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, openWorldHint=true) by disclosing the required scope registre:write, that idempotency_key is sent as the Idempotency-Key header with 24 h retention and replay semantics, fail-closed behavior for non-Québec cadastres, and that the caller must supply their own Bearer API key. Billing behavior per document, per test key and per 4xx/5xx is also spelled out.

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 route and purpose, which is good, but the body is roughly doubled in length by full English/French duplication and by three separate billing sentences that restate the same fee logic. The useful content is there, but it is not tight.

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 billable write-scoped external call with no output schema, the description covers auth, scope, idempotency, edge-case failure mode and the full cost model, including the Registre's separate 1,50 $ charge. An agent has everything needed to invoke it correctly and predict the consequences.

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 the baseline is 3; the description earns an extra point by adding real semantics for idempotency_key (header transport, 24 h store, retry returns the stored answer) and by explaining that cadastre non-default values fail closed.

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

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

States a concrete verb+resource (retrieve the cadastral plan of one lot in the Cadastre du Québec) and names the underlying route POST /v1/plans. An agent can tell it apart from acte_get or lot_get by the document type. It stops short of explicitly contrasting itself with those siblings, which keeps it at 4 rather than 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?

Usage context is only implied: 'A stored plan has no Registre fee; other cadastres fail closed' tells the agent a constraint but not when to prefer this tool over acte_get, lot_get, or registre_index_request. No explicit when-not or alternative routing is given.

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?

Goes well beyond the annotations (which only say idempotent, non-destructive, open-world): discloses the registre:write scope, the required Bearer API key, the 24 h Idempotency-Key retention with stored-answer replay, and a precise billing model ($0.99/doc on live keys, free on test keys and 4xx/5xx, plus the Registre's own $1.50 fee). These are exactly the cost and auth facts an agent needs before triggering a paid write.

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 operation and next step are front-loaded, but the description is roughly doubled by verbatim English/French duplication, making it long and repetitive to parse. The billing and fee sentences are useful but add further bulk to a three-parameter write 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?

With no output schema, the description compensates by telling the agent what comes back (job_id) and what to do next (poll job_get). Auth, scope, idempotency, and the full cost breakdown are all present, leaving nothing material an agent needs before calling it.

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 real meaning the schema lacks: idempotency_key is transmitted as the Idempotency-Key header, retained 24 h, and a same-key retry returns the stored answer. It also clarifies that rf_account_id defaults to the organization's own Registre account, which the schema states only tersely.

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

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

States a concrete verb and resource ('Queues an index of immovables for one lot') plus the underlying route and the exact account it runs against. It also names the follow-up tool (job_get), so an agent can distinguish it from read tools like lot_get or document_get 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 a clear workflow: call this, receive job_id, then poll job_get. It does not address when to use this versus alternatives such as lot_resolve or plan_get, nor any preconditions like resolving a lot first, so it stops short of full 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?

Goes well beyond the annotations: discloses that idempotency_key is sent as the Idempotency-Key header with a 24h window and stored-answer replay, requires the caller's own Fonciq API key as a Bearer token, and details that creation is free while each pulled index costs 0,99 $ plus a third-party Registre fee of 1,50 $ that Fonciq does not collect. This is exactly the cost/auth/idempotency context an agent needs before a write.

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 and well-organized, but every sentence is duplicated verbatim in English and French, and the billing explanation is restated three times across the two halves. Roughly half the tokens are redundant for a monolingual reader.

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 burden of return behavior; it explains the async nature (index pulled later, delivered by webhook) and covers auth, cost and idempotency. It stops short of describing what the POST response contains or what the webhook payload looks like.

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 80%, so the baseline is 3; the description adds real value on top by explaining that idempotency_key becomes an HTTP header with 24h retention and that cadence means weekly or daily re-checks against a baseline snapshot. It does not clarify rf_account_id beyond the schema, keeping it from a 5.

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+resource (POST /v1/watches creating a scheduled re-check of a lot's index) and scopes it with cadence and webhook delivery. It implicitly distinguishes itself from one-shot siblings like registre_index_request by noting 'The Registre has no push feed', though it never names an alternative 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?

Usage context is only implied: the 'no push feed' remark suggests this is the polling alternative to ad-hoc index requests, and cadence weekly/daily hints at recurring need. There is no explicit 'use this when…, use registre_index_request when…' routing against the 13 siblings.

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