normi

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

Annotations already declare the write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the safety bar is lower. The description adds real context beyond that: automatic estimate computation for Maison/Appartement, metadata-only storage for other types, and a credit cost of 10 vs 2. It does not mention auth requirements or whether repeated calls create duplicates.

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 action and the key conditional cost, and reasonably compact. Slightly redundant: the credit cost is stated twice (inline parenthetical and a trailing 'Cost:' line), which costs a sentence without 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?

With no output schema, the description steps in to say it returns the created property record with estimate fields, which is what an agent needs. Credit pricing and the estimate-vs-metadata branching are covered. It stops short of covering duplicate handling, idempotency behavior, or any error conditions.

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 every parameter is already documented in the schema, including the type_local enum. The description's required/optional listing merely restates what the schema's required array and field descriptions already encode, adding no format or constraint detail beyond it. 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 verb (Add) and resource (property to portfolio), clearly distinguishing it from the sibling update_portfolio_property, delete_portfolio_property, and list_portfolio_properties tools. An agent can identify the create operation 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?

Implies usage (adding a property to your portfolio) but never states when to prefer this over siblings like estimate_property_value or update_portfolio_property. It does disclose a type-conditional behavior (estimate computed for Maison/Appartement, metadata only otherwise), which is useful, but no explicit when-not guidance or named alternatives.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely non-derivable context: the 10-credit cost, the at-least-one-location constraint, and the exact decade buckets returned. It stops short of describing pagination or result limits, keeping it out of the top tier.

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 operation, then organized into labeled sections (buckets, required/optional, example, cost) that are easy to scan. The example-output line and its interpretation earn their place, though the block is longer than strictly minimal.

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 supplying a concrete example output row plus interpretation, the full set of decade bucket keys, the location requirement, and the cost. An agent has everything needed to invoke 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%, which normally anchors a 3, but the description adds meaning the schema lacks: the schema declares no required fields, while the description states 'REQUIRED: at least one location — code_postal, commune, or code_departement', which is a real constraint not encoded anywhere in the schema. That lifts 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?

States a precise verb (Get median prix/m²) and a specific grouping dimension (construction decade) for a location, which no sibling tool covers — nothing else in the sibling list analyzes building age. An agent can select this 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?

Provides a clear use context ('advising whether older buildings trade at a discount and how much'), which tells the agent when this is relevant. However, it never names an alternative (e.g., analyze_dpe_price_premium or get_zonal_price_distribution) or states 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?

Annotations already declare readOnlyHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the credit cost, the 'all buildings' counting rule, and the par_usage bucket semantics (residentiel = collectif + individuel).

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 purpose, then constraints, then parameter guidance, then a concrete output sample. Dense but every block earns its place; the enum enumeration for par_usage is slightly verbose but relevant to interpreting results.

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 supplying a worked example output covering top-level keys and nested par_tranche/par_usage maps, plus the required-input rule and cost. An agent has enough to call and interpret 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 baseline is 3, but the description adds real meaning: it states the 'at least one of' requirement and calls out code_commune_insee as most precise to avoid same-name ambiguity. Minor gap: code_postal appears in the schema but is omitted from the location list in the description.

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 ('Get aggregate building stock characteristics') plus a scoped resource and names its data source (BDNB national database). The 'aggregate' framing and 'Counts ALL buildings (not just those with DVF transactions)' distinguishes it from row-level siblings like get_building_characteristics.

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?

Clearly states the precondition ('at least one location') and ranks the location parameters by precision, and carves out its scope versus DVF-based tools. It does not explicitly name a sibling alternative the way a 5 would, so it stops at clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond annotations: the 10-credit cost, the at-least-one-location constraint, and the shape of the returned distribution, which the annotations do not convey.

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 purpose, then constraints, then a compact example and cost line. Formatting is scannable and every element earns its place; the example JSON is slightly long but directly useful given there is no output schema.

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

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

With no output schema, the description compensates by showing the response shape (count, distribution, pct) in an example. Required-parameter semantics are fully specified. It lacks coverage of error behavior or result-size limits, but nothing essential for a correct call is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema cannot express: the cross-parameter requirement that at least one of code_postal/commune/code_departement be supplied (the schema marks zero required fields). It also clarifies that distribution is per energy class A–G.

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 ('Get') and resource ('DPE class distribution') with a clear scope ('for a location') and spells out the return payload (count and share of A–G ratings). It is distinguishable from siblings like analyze_dpe_price_premium and analyze_dpe_price_and_thermal_risk, which concern price rather than class distribution.

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 operating context: REQUIRED at least one location parameter (code_postal, commune, or code_departement), OPTIONAL type_batiment and date_debut filters, plus a worked example and a cost figure. It does not name alternative tools or when-not-to-use conditions, so it stops short of a 5.

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

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

Annotations only declare readOnlyHint and openWorldHint, but the description adds materially: cost (10 credits), the Alsace/dept 67-68 zero-result limitation, the 200m nearest-DPE matching caveat that class gaps are indicative, and the data-coverage limitation pointers for prime_verte. These are real behavioral traits an agent needs and are not in the 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?

Front-loads the one-line purpose, then structures detail into numbered analyses, a when-to-use block, param requirements, and caveats. Slightly long and the numbering (1, 2 then 3) is a bit uneven, but nearly every line carries information the caller needs for a multi-output analytical 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 no output schema, the description fully explains the return shape (two distinct analyses, threshold/coverage metric, sieve share with annual trend), the constraints, the data limitations, and the cost. Nothing essential for correct invocation or interpretation 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 100%, so the per-parameter descriptions are already present. However, the schema lists 0 required parameters, while the description supplies the true constraint ('REQUIRED: at least one location — code_postal, commune, or code_departement'), which is a meaningful addition the schema does not encode. It also clarifies the Maison|Appartement option but adds little else beyond schema syntax.

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+resource ('Combined DPE market analysis — price per energy class AND thermal sieve stock') and enumerates exactly what the three returned analyses are. It also names and contrasts with the closest sibling, analyze_dpe_price_premium, so an agent can distinguish them 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?

Has an explicit 'WHEN TO USE THIS vs analyze_dpe_price_premium' block that gives the selection condition for each ('full DPE snapshot' vs 'how much more is an A vs the local median'). This is textbook when-to-use/when-to-use-the-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?

Adds substantial behavior beyond the readOnly and openWorld annotations: exact cross-referencing method, 200m and 10-year matching window, output structure, known limitations, and cost in credits. This gives the agent a clear picture of how results are produced and their caveats.

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 method, then uses labeled blocks for required/optional, output shape, limitations, and cost. It is slightly long but each element—method detail, output shape, cost—is necessary given no output schema and the analytical complexity.

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 no output schema, the description supplies the output shape, methodology, limitations, and cost, and it states the required input constraint. It covers what an agent needs to invoke and interpret 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 descriptions cover all three parameters at 100%, but the description adds crucial semantics: one of code_postal or commune is required even though the schema marks no required fields, and department-level analysis is too broad. It also clarifies type_local's role and default.

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 'Analyze' and resource 'price premium or discount of energy performance ratings in a market', and the method paragraph distinguishes it from pure DPE distribution tools. However, it does not explicitly differentiate from the closely named sibling analyze_dpe_price_and_thermal_risk, leaving a possible overlap unaddressed.

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?

Specifies required location inputs (code_postal or commune) and optional type_local, and explains that department-level analysis is too broad for meaningful comparison. It does not name alternative tools or say when to prefer this over analyze_dpe_distribution or analyze_dpe_price_and_thermal_risk.

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/openWorldHint, so the description adds real behavioral context: a per-call cost of 10 credits, the DVF 2014–2025 data cadence with a months ≥ 12 reliability caveat, and a constraint the schema does not encode (at least one location filter is required despite zero required params).

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 purpose and routing, then required/optional/returns/example/notes in scannable sections; every block carries information. The Returns list and example add some length, but no sentence is 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?

With no output schema, the description fully describes the return payload (volumes with YoY, trend direction, activity level, seasonality, market signal) and also covers cost, data coverage, and the implicit required-filter rule. 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 only 20%, so the description must compensate — it documents the commune example ('PARIS 11'), the role of code_departement/code_postal as alternative location filters, type_local as a property-type filter, and the months default/max. It does not clarify the distinction between code_postal and code_departement or behavior when multiple filters are combined, so it falls short of full compensation.

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

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

States a specific verb+resource ('Monthly transaction volume time series') and immediately distinguishes itself from the closest sibling by naming score_market_health and the question each answers. An agent can pick between them without opening either 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?

Explicit when-to-use vs when-not-to-use, with concrete trigger questions ('show me how volume has evolved' / 'is there seasonality?' vs 'is this market good or bad?'), plus the alternative tool named for the other case. Nothing is left to inference.

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

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

Goes beyond the readOnlyHint/openWorldHint annotations by disclosing a real behavioral constraint (radius_m > 1000m is silently restricted to the last 12 months) and a cost of 5 credits per call. It also lists the return fields, though it doesn't say how results are ordered or capped.

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 purpose, then uses labeled sections (REQUIRED, Examples, Returns, Note, Cost) that are easy to scan. Three examples are arguably one more than needed, but each illustrates a distinct filter mode, so little is wasted.

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 14-parameter tool with no output schema, the description supplies the missing pieces: the required-filter rule, the returned metric set, the radius time-window caveat, and the per-call cost. An agent can invoke this correctly without opening 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 coverage is 100%, so the baseline is 3, but the description adds genuine semantics: the OR-relationship among location filters, the latitude+longitude pairing, the uppercase 'PARIS 11' convention for commune, and the 500m default radius. It adds real value over the schema descriptions without restating 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?

States a specific verb and resource plus the exact output metrics (avg/median prices, price per m², surface areas), which lets an agent distinguish it from sibling analytics tools like analyze_price_trends or get_market_overview. It stops short of explicitly naming which sibling to use instead for trend or overview questions.

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 a hard precondition ('You MUST provide at least one location filter') and enumerates the four acceptable filter forms, then gives worked examples for each. It does not state when to prefer a sibling tool (e.g. compare_locations or estimate_property_value), so no exclusions are covered.

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 openWorldHint=false, and the description adds meaningful context beyond them: the credit cost (10 credits/call), the underlying data coverage (DVF 2014–2025, annual cadence), and default date behavior. It stops short of describing pagination or output format limits.

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 purpose, then cleanly sectioned into REQUIRED / Optional / Returns / Example / Note / Cost. Every block is useful, though the Returns list is somewhat long and could be tightened.

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 12 parameters and no output schema, the description carries a lot of burden and handles it: it documents return structure, defaults, data-coverage limitations, and cost. A few parameters (radius_m, exclude_vefa, exclude_bulk_sales) are left entirely to the schema, but overall it is nearly complete for a tool of this complexity.

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 83%, so the baseline is 3, but the description adds real value: it encodes the cross-parameter constraint ('at least one location filter') that the schema cannot express since required=0, explains defaults for granularity and date range, and gives a concrete example payload. This goes beyond the per-field schema text.

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: 'Analyze price evolution over time,' which clearly separates it from siblings like get_zonal_price_distribution (static distribution) or analyze_market_statistics (aggregate stats). It does not explicitly name the sibling tools it competes with, so it falls short of the 5 benchmark for sibling 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?

Gives clear usage context ('essential for market timing and investment decisions'), the mandatory location-filter constraint, and a reliability caveat (use windows ≥ 12 months). It never names alternative tools to use instead, so no explicit exclusions are present, but the when-to-use context is well covered.

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 openWorldHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: the null return when INSEE suppresses a commune's income figure, the 5-credit cost, and the exact data sources. It does not cover auth or pagination, but for a read-only analytics call this is substantially richer than the annotations 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 definition is front-loaded with the metric in the first sentence, then blocks for required inputs, unsupported scopes, return values, and cost. Each section is short and earns its place; no filler or repetition of the title.

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 correctly enumerates the returned fields (ratio_prix_revenu, prix_bien_median, revenu_median_annuel_uc, annee_reference) and explains the null case. Together with the locator constraints and cost disclosure, an agent has everything needed to call and interpret this 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%, so the baseline is 3, but the description adds a cross-parameter constraint the schema does not encode — 'You MUST provide one of' three locators — despite zero parameters being marked required. It also clarifies that code_commune bypasses commune resolution and rejects lat/lon and departement scopes, which the schema does not express.

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 metric — 'how many years of median income to buy the median property here' — and names the exact data sources (DVF price/surface medians crossed with INSEE Filosofi median income). It also distinguishes itself from analyze_market_statistics and find_property_comparables by naming them as the right tools for the unsupported scopes.

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

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

It gives explicit when-to-use conditions (one of code_postal, commune, code_commune), explicit when-not conditions (code_departement alone, latitude+longitude), and justifies the exclusions with reasoning about commune boundaries and income aggregation. Alternatives are named for the excluded scopes, 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?

Annotations provide readOnlyHint=true and openWorldHint=false, but the description adds crucial context beyond this: it specifies the return contents, the 24-month DVF window, the cost of 10 credits per call, and important methodological caveats (excludes certain costs, rent type). This goes well beyond the 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?

Well-structured with required/optional sections, clear bullet points, and a short cost note. However, the description is somewhat verbose and could be slightly more front-loaded with the core purpose before diving into details.

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 lack of an output schema, the description compensates by detailing the return values (latest 24-month DVF window, median sale price/m², ANIL rent/m², estimated gross yield, confidence interval, data-quality flags). It also covers scope limitations and cost. Complete for an agent to invoke 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%, so the schema already documents parameters. The description adds value by explaining the INSEE code format and examples, clarifying that appartement_profile applies only to apartments, and specifying defaults and enum meanings.

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 (Estimate) and resource (gross rental yield) with explicit data sources (ANIL asking-rent indicators, DVF sale prices). Clearly distinguishable from siblings like estimate_property_value or analyze_market_statistics.

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 frames the scope as commune-level and lists what it excludes (taxes, financing, vacancy, maintenance, management), guiding the agent away from misuse. However, it does not explicitly name alternative sibling tools that might be more appropriate for property-specific valuation.

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?

Adds substantial context beyond the readOnly/openWorld annotations: cost (10 credits per call), DVF data coverage window (2014–2025, annual cadence), and a reliability caveat (use ≥12 month windows). These are exactly the operational facts an agent needs before committing a paid call.

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 purpose, then uses labeled sections (REQUIRED / Optional / Returns / Example / Note / Cost) so an agent can scan quickly. Two examples and the Returns block are slightly redundant but each carries distinct 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 compensates by enumerating the per-location return fields (transaction count, median price/m², YoY change, rankings). Combined with the cost, data-range, and default notes, nothing needed to call or interpret the 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 coverage is already 100%, so the baseline is 3; the description goes further by clarifying that each location object takes either {code_postal} or {commune}, restating the defaults, and showing two worked invocation examples that illustrate the alternative shapes.

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 (compare), resource (2-5 neighborhoods/locations), and scope (side-by-side, 2-5) in the first line. The 'investment location decisions' framing distinguishes it from single-location siblings like analyze_market_statistics or estimate_property_value.

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 case ('perfect for investment location decisions') and concrete invocation examples for both code_postal and commune forms. It does not, however, name alternatives or state when not to use it versus e.g. find_property_comparables.

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 write/non-idempotent/non-destructive; the description adds substantial behavioral context beyond that — the plan entitlement gate, a hard rate limit (20 active alerts per key), the asynchronous side effect (a POST to webhook_url when a matching transaction appears), and the credit cost. This is exactly what the description is for.

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?

Information is front-loaded (purpose, then requirements, then inputs, then behavior, then cost) and every line earns its place. Required vs optional grouping makes the constraints scannable with no redundant prose.

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 write tool with no output schema, the description covers the entitlement, quota, required inputs, the webhook delivery behavior, and cost. An agent has everything needed to decide whether and how to call it; the lack of an output schema is adequately compensated by the stated side effect.

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 the cross-field rule that at least one location filter (code_postal, commune, code_departement) is required — a conditional constraint the schema only encodes piecemeal — and separates required from optional params.

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 states a specific verb (create) plus resource (webhook alert) and the trigger condition ('new DVF transactions matching your criteria'). The name and description cleanly separate it from list_market_alerts, update_market_alert, and delete_market_alert without needing 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?

It gives real context for using this tool: Pro/Enterprise plan required, max 20 active alerts, and the required inputs. However, it never routes the agent to alternatives (e.g. use update_market_alert to modify an existing alert, list_market_alerts to view current ones), so the sibling comparison is left 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 already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered; the description still adds value by stressing 'Permanently' (irreversibility), naming the plan requirement, and disclosing the exact return payload. It does not, however, cover any rate limits or downstream effects on webhook deliveries.

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 short and front-loaded, with required-param, return, and cost lines that are easy to scan. It is slightly redundant, repeating the Pro/Enterprise requirement twice and listing 'Cost: 0 credits' for a plan-gated delete, but nothing is truly wasteful.

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

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

For a one-parameter destructive tool this covers the essentials: scope, plan prerequisite, exact return value, and cost. With no output schema the description fills the return-value gap, though it omits what happens to already-fired webhooks or error behavior.

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 a single parameter and 100% schema description coverage, the schema already fully documents 'id'. The description only restates the requirement ('REQUIRED: id (alert ID)') without adding format, source, or constraint detail beyond the schema, so the baseline of 3 applies.

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

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

The description opens with a specific verb+resource ('Permanently delete a webhook alert'), and the notion of 'webhook alert' plus the 'delete' verb clearly separates it from create_market_alert, update_market_alert, and list_market_alerts. An agent can place it among its siblings 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 states a gating prerequisite ('Requires Pro or Enterprise plan'), which is useful usage context, but it gives no explicit when-to-use vs when-not guidance and does not point to update_market_alert as the non-destructive alternative. Usage is implied by the verb rather than 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds value beyond them by spelling out the permanence of the effect, the success return shape ('{ deleted: true }') despite no output schema, and zero credit cost.

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?

Three short lines, front-loaded with the action and the permanence warning, then required param, return, and cost. No sentence is wasted and nothing important is buried.

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 destructive tool with annotations covering the safety profile, the description supplies everything needed: the permanent nature of the deletion, the required input, the success response shape, and the cost. Nothing required 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?

Only one parameter with 100% schema description coverage, so the schema already documents 'id' fully. The description's 'REQUIRED: id (property ID)' merely restates it without adding format, source, or lookup guidance, 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 verb and resource ('Permanently delete a property from your portfolio') with the scope 'from your portfolio', which cleanly separates it from sibling delete_market_alert and from the non-destructive update_portfolio_property. An agent can select 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?

The adverb 'Permanently' implicitly warns the agent that this is not a reversible operation, which is useful context for when to choose it, but no alternative (e.g., update_portfolio_property for archiving) or precondition is named. 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 only supply readOnlyHint and openWorldHint; the description adds substantial behavioral context on top: a 10-credit cost, a no-charge path for unsupported input, aggregate-only output that never exposes addresses or owners, the matching methodology (cadastral section + plan, then normalized-address fallback), and the anchoring of the 24-month window to the latest available DVF 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 structure is front-loaded and scannable (purpose, REQUIRED, OPTIONAL, definition, returns, cost), and nearly every sentence carries load-bearing information. It runs slightly long with the matching-method detail, but that detail is defensible for a statistical tool with methodology caveats.

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 enumerating the returned aggregate indicators (flip rate, median gross margin, median margin percentage, median holding period, matching-method counts) and explicitly stating what is never returned. Combined with cost and the apartment edge case, an agent has everything needed to call and interpret this 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%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the rationale for why apartments are unavailable ('DVF parcel/address matching can't tell flats in the same building apart') and confirmation that code_commune is a compatibility alias rather than a DVF raw commune fragment. It also clarifies the default (Maison) more explicitly than 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 first sentence names a specific verb ('Detects') and a specific, non-obvious resource ('short-hold resales ("flips") in one French commune'), and the body defines exactly what counts as a flip. No sibling tool (search_property_transactions, analyze_price_trends, etc.) covers flip detection, so the agent can route here unambiguously.

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 partial when-not case by explaining that type_local="Appartement" returns available:false and is not charged, which usefully steers the agent away from a wasted call. However, it never names alternative tools or states when an agent should prefer raw transaction search or market analysis over this aggregate detector, so usage 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?

Far exceeds the annotations (readOnlyHint/openWorldHint). It discloses the cost (10 credits), the null-return threshold (<3 comparables), the confidence semantics ('not a calibrated probability'), the interval methodology (backtest on 2,000 masked DVF sales, P25/P75, cohort-based width), and DVF coverage 2014–2025. Nothing here contradicts 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?

Front-loaded well (purpose first, then routing, then required params). However, the interval/cohort methodology paragraph is dense and lengthy, and largely restates what the return object would convey. It earns partial credit but is more verbose than an agent needs to choose and call the 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 read-only AVM tool with no output schema, the description covers inputs, outputs, failure mode, cost, and confidence caveats thoroughly. Left slightly incomplete on error semantics beyond the <3 comparables case and any rate-limit/permission context, but overall strongly complete.

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 baseline is 3. The description adds meaning beyond the schema: which params are REQUIRED, defaults (Appartement, 500m, 18mo), the fallback purpose of code_postal/commune, and the '±1 tolerance' context for pieces. It does not add syntax beyond the schema but does add decision-relevant context.

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 an automated valuation (AVM) for a property') and immediately distinguishes itself from the closest sibling, find_property_comparables, by contrasting outputs (AVM summary vs raw comparable transactions). An agent can route correctly without opening either 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 names the alternative tool and the condition that selects it (raw comparables with similarity scores). It also gives a recovery tip ('increase radius_m or max_age_months') and a data-recency condition ('use max_age_months ≥ 12'). It lacks a clear 'do not use when' for the many other analysis siblings, so it falls just short of 5.

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

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

Beyond the readOnly/openWorld annotations, the description discloses the sparse-result fallback (extend to 36 months, then 2 km), the ±1 pieces tolerance, the ±20% surface convention, the cost (10 credits per call), and the exact return payload. These are meaningful behavioral traits an agent cannot derive 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?

Front-loaded purpose followed by clear Required/Optional/Returns/Example sections makes it scannable for a 12-parameter tool. It is somewhat long and there is mild duplication with the schema (defaults, radius, limit) plus the throwaway '#1 tool' line, but the structure earns its length.

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 correctly documents the return shape (similarity scores, distance/age, adjustment suggestions, estimate with confidence interval) and gives a concrete worked example. For a complex, high-parameter tool, nothing critical is left to guesswork.

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, but the description adds real semantic context: 'typically ±20% of target' framing for the surface bounds, the ±1 room tolerance, and the note that max_age_months matches estimate_property_value's default and drives the widening logic. A few items (radius default, limit cap) merely echo 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+resource ('Find comparable properties for valuation'), which an agent can clearly separate from sibling tools like estimate_property_value or search_property_transactions. It does not explicitly contrast its role against those siblings, and the '#1 tool for real estate agents' tagline is marketing fluff, but the core purpose is 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 lays out required vs optional inputs and operational fallback behavior, so usage is implied. However, it never says when to reach for this tool over estimate_property_value (which is only referenced for a shared field definition) or when a plain property search suffices, leaving the when-to-use decision 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 readOnlyHint/openWorldHint annotations, it discloses the match method (nearest BDNB building within 200m), the failure mode ('returns null + refunds credits if no building found within 200m'), and the exact cost (2 credits). This is exactly the behavioral 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?

Front-loaded with purpose, then labeled sections (Returns, REQUIRED, Match method, Workflow, Example, Cost). The example and cost lines are compact and each sentence carries distinct information with no 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?

With no output schema, the description compensates by enumerating the returned fields and showing a sample response shape, and it documents the null/refund edge case. An agent has everything needed to call and interpret the tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it names the upstream source of transaction_id and shows the expected string shape via an example call. That goes beyond the schema's bare 'DVF transaction ID' label.

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+resource ('Get physical building characteristics') and names the exact source database (BDNB) and the triggering entity (a DVF transaction). The listed return fields make it immediately distinguishable from siblings like score_renovation_potential or analyze_building_stock.

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

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

Explicit workflow instruction: 'call search_property_transactions first → use an "id" from the results as transaction_id here.' It also tells the agent exactly where to source the required parameter, leaving no inference needed about ordering or prerequisites.

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 and openWorldHint, so the description carries the rest and delivers: per-call cost (10 credits), the credit savings vs. alternatives, and a non-obvious behavioral constraint that the health score is unavailable for lat+lon-only searches. It also gives score interpretation bands (0–30 Calme … 81–100 Très actif), which meaningfully describe output behavior.

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 one-line purpose, then organized into required/optional/returns sections with clear headers. Slightly long with some restatement (the health requirement appears twice), but every block is scannable and useful given no 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?

With no output schema, the description fully documents the return shape (stats, trend, health components), the location-filter requirements, the health limitation, cost, and score interpretation. Nothing an agent needs to invoke or interpret the result is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real semantics beyond the schema: it notes commune must be uppercase with the 'PARIS 01'–'PARIS 20' convention, gives concrete examples per filter, and crucially states that health requires code_postal/commune/code_departement (not lat+lon). That cross-parameter constraint is not derivable from the schema 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?

States a specific verb, resource, and scope: 'Get a complete market brief for a location in one call — stats + trend + health score.' It explicitly distinguishes itself from siblings by naming the three tools it consolidates (analyze_market_statistics, analyze_price_trends, score_market_health). An agent can route to 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?

Explicit when-to-use ('first tool for any "how is the market in X?" question') plus named alternatives it replaces and the cost rationale (saves 15–25 credits). This is the strongest form of 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?

Discloses a hidden side effect beyond the annotations: the estimate is automatically refreshed (a write, consistent with readOnlyHint=false) when it is older than 30 days and the property is a Maison or Appartement, and specifies the 10-credit cost. This conditional mutation and cost detail would be impossible to infer from the structured fields 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?

Front-loaded with the core action, then conditions, required param, return value, and cost in terse blocks. The credit cost is stated twice ('10 credits' and the Cost line), a minor redundancy, but overall efficient.

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, yet the description specifies the return payload (property record + estimate_refreshed boolean) and covers the refresh conditions and cost, so an agent has everything needed to invoke it correctly without surprises.

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 sole parameter is already documented, but the description adds real meaning by stating the id's provenance (from list_portfolio_properties or add_property_to_portfolio) and marking it REQUIRED, which is beyond the bare 'Property ID' schema text.

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 a single portfolio property by ID') and the word 'single' implicitly contrasts with the sibling list_portfolio_properties. It does not explicitly name the alternative as a contrast, 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?

The description tells the agent where the required id comes from (list_portfolio_properties or add_property_to_portfolio), which is useful sourcing context, but gives no explicit when-to-use vs when-not guidance relative to siblings like list_portfolio_properties or update_portfolio_property.

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 cover read-only and open-world access, so the description carries extra weight and delivers: it discloses the server-side INSEE_API_TOKEN prerequisite, a 2-credit cost, and the important output-scoping fact that only the main establishment (siège) is returned, not all establishments. It omits error behavior for invalid SIRENs or rate limits, keeping 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 one-line purpose, then returned fields, requirement, example, caveat, and cost, each on its own line. The 'REQUIRED: siren (9-digit SIREN number)' line partially duplicates the schema, but the layout is scannable and nothing is padded.

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 naming the returned fields (legal name, NAF code, address, creation date, administrative status). Combined with the auth prerequisite, cost, and siège-only scoping, an agent has everything needed to call and interpret this 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 schema already states '9 digits', so the baseline is 3. The description goes slightly beyond by restating the requirement and supplying a concrete example value with the expected response shape, which clarifies the expected format and output keys.

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 (get), resource (real estate business details), and the exact retrieval key (SIREN via INSEE API), plus enumerates the returned fields. It implicitly separates itself from search_real_estate_businesses by requiring an exact identifier, but never names or contrasts that sibling 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 is implied: the description says details are fetched by SIREN, so an agent infers this is the follow-up to a lookup that already produced a SIREN. There is no explicit when-to-use statement, no when-not-to-use, and no pointer to search_real_estate_businesses for discovery, even though that sibling exists.

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 openWorldHint=false, and the description adds substantial value beyond that: a 15-credit cost, the fact that it returns structured JSON rather than an image, and the conditional MCP-Apps interactive-map rendering behavior. It also discloses the scope-filter requirement and default date window.

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 purpose, then grouped bullets for required/optional/returns, then when-to-use, then an example. Well structured and mostly tight, though the 'not a rendered map or image' caveat is repeated in two places and could be stated once.

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, but the description compensates fully by enumerating the per-zone return fields (centroids, median/avg price/m², transaction count, relative position label), and it covers cost, defaults, and the scope-filter constraint. 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%, so baseline is 3, but the description adds real meaning the schema does not encode: the schema lists no required parameters, yet the description states at least one scope filter (code_departement or commune) is REQUIRED, plus the 'returns all arrondissements' behavior for commune. It adds little beyond the schema for group_by/type_local/min_transactions.

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?

Starts with a specific verb+resource ('Get price statistics aggregated by postal code or commune zones') and immediately disambiguates from a rendered-map tool. The sibling set contains several analysis tools, and the description's emphasis on zonal aggregation vs. whole-market statistics makes the boundary reasonably clear.

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?

Provides an explicit 'Use this when you need to' block with three concrete scenarios plus a 'Do NOT call this expecting a rendered image' exclusion. It stops short of naming a specific sibling alternative (e.g., compare_locations or analyze_market_statistics) for the cases where a non-zonal comparison is wanted.

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?

With readOnlyHint and openWorldHint already declaring the safety profile, the description adds genuine context beyond annotations: the plan gating (Pro/Enterprise), the zero-credit cost, and the fact that inactive alerts are included. The only gap is return format, which no output schema covers.

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 short, front-loaded sentences with no filler. The plan requirement is stated twice ('Requires Pro or Enterprise plan' and 'Pro/Enterprise plan required'), a minor redundancy that keeps it from 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 no-parameter, no-output-schema list tool, the description covers scope (active and inactive), access constraints (plan tiers), and cost. It does not describe the returned alert fields, a small gap given the absence of 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?

The tool takes zero parameters, so there is nothing for the description to document beyond what the (empty) schema already shows. Baseline 4 applies; no parameter detail is needed or omitted.

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: 'List all webhook alerts.' The scope qualifier 'active and inactive' and 'for this API key' further narrow it, so an agent can distinguish it from create/update/delete_market_alert without opening a schema. It stops short of naming an alternative, keeping 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?

The plan requirement ('Requires Pro or Enterprise plan') gives a precondition, but the description never states when to prefer this tool over siblings like create_market_alert or update_market_alert. Usage is implied by the list verb 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 the read-only and closed-world profile, but the description adds real value beyond them: the array is ordered by creation date newest-first, estimates are cached rather than live, and the call costs 0 credits. Only the absence of pagination/result-size behavior keeps it from 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?

Three short, front-loaded blocks: what it returns, the ordering detail, then the routing hint and cost. No sentence is redundant.

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

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

With no output schema, the description usefully describes the return shape (array of property records, newest first) and the cache caveat. It stops short of mentioning pagination or list size limits, a minor gap for a list endpoint.

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 the baseline of 4 applies; there is no parameter syntax or meaning the description could add.

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 ('List all properties in your portfolio') plus the scope qualifier 'with their cached estimates', which immediately differentiates it from the single-property sibling get_portfolio_property.

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 names the alternative tool and the condition that selects it: 'use get_portfolio_property for a specific property to trigger a refresh if stale'. An agent can route correctly without 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?

Goes well beyond the readOnlyHint/openWorldHint annotations: discloses cost (20 credits, refunded when nothing found), result cap (max 50, newest first), ordering, the scope field, a chaining id, and precise price_evolution semantics (null unless a repeat sale of a comparable property).

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 purpose and the required combinations before returns and workflow, and uses headers/examples that scan well. It is somewhat long with a few overlapping return bullets (scope, id, fields) that could be tightened.

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 fully carries the burden: it enumerates returned fields, ordering, cap, scope values, price_evolution edge cases, and the downstream chaining pattern. Nothing essential to invoke or interpret the call 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 per-parameter docs already exist, but the description adds the critical combination semantics that the schema's zero-required-params leaves ambiguous (address+code_postal vs. section+no_plan+code_commune) plus concrete examples. Some overlap with the schema's code_commune note.

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+resource ('transaction history for a specific address') and immediately clarifies scope modes (address vs. street vs. cadastral parcel). An agent can tell this is the address/parcel-level transaction lookup rather than the broader sibling search_property_transactions.

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 required parameter combinations, explains the fallback behavior when no sale exists at a number, and provides a workflow chain to get_building_characteristics. It does not name sibling tools like search_property_transactions to explicitly route between alternatives, which is the only gap.

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 readOnlyHint/openWorldHint annotations by disclosing the cost ('1 credit per call'), the ranked nature of results, and the deliberate no-silent-disambiguation behavior ('Paris' returns all 20 arrondissements). These are exactly the traits an agent needs before invoking it in a chain.

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 purpose, then usage, then behavior and cost in three tight paragraphs. The example strings are repeated from the parameter schema, a minor redundancy, but nothing else is wasted.

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 describing returns and does so ('ranked canonical commune, postal-code, department and INSEE filters'). Combined with cost and disambiguation behavior, an agent has everything needed to call and chain it correctly.

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

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

Schema coverage is 100% and the single parameter is fully documented, so the baseline is 3. The description adds meaning by enumerating accepted input forms (postal codes, communes, arrondissements) and accented/abbreviated variants like 'st etienne', which the enum-less schema cannot express.

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 (resolve), a precise input domain (free-form French administrative locations) and the output (canonical Normi filters). It is clearly distinguishable from all siblings, which are analysis/market tools rather than a geocoding normalizer.

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 says to 'use this before another Normi tool when the location is informal, accented, abbreviated, or ambiguous', giving both the trigger condition and its role as a prerequisite step. No alternative tool competes for this job, so no exclusions are needed.

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 openWorldHint=false, and the description layers on genuinely useful behavioral facts: the 10-credit cost, the null-return edge case when fewer than 10 transactions exist in 6 months, and the score-band interpretation. Cost and failure-mode disclosure are exactly the 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?

Front-loaded one-line purpose, then clearly sectioned WHEN TO USE / REQUIRED / Optional / interpretation / Returns / Cost. Dense but every block carries distinct decision-relevant 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?

No output schema exists, so the description compensates by naming the return fields (score, label, components, data_quality) and the null case. Combined with the location requirement and cost, an agent has everything needed to call and interpret the tool.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns above it by restating the at-least-one-location constraint (only partly present in the schema, on code_postal alone) and by explicitly excluding latitude+longitude, which the schema does not mention at all.

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+resource ('Instant 0–100 composite score for comparing markets') and immediately distinguishes itself from the sibling analyze_market_activity. An agent can identify the tool's output form (a single comparable number) 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?

Explicitly names the alternative (analyze_market_activity) and the deciding conditions: use this for a single comparable number/rank/go-no-go, use the sibling for volume trends over time or seasonality. This is textbook when/when-not 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 cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds non-obvious behavior beyond them: the 10-credit cost, the null-on-insufficient-data rule, and what the score actually encodes. Return format is conveyed via an example rather than a schema, so remaining gaps are minor.

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 purpose and scoring logic, then required/optional params, then example, caveat, and cost. Every block earns its place, though the example output plus the duplicate 'Note' line adds some length.

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, yet the description supplies an example return object with all fields, their meaning, the score encoding, the insufficient-data edge case, and the cost. An agent has everything needed to invoke and interpret this 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%, so the baseline is 3. The description does add one thing the schema cannot show: because required is empty in the schema, its 'REQUIRED: at least one location' and 'OPTIONAL: type_local' labeling supplies the real constraint. That is a modest but genuine addition on top of fully documented parameters.

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+resource ('Identify renovation opportunities') and pins the cohort precisely: 'pre-1975 buildings priced below the area median.' The score range and its drivers (discount + older stock) make it distinguishable from siblings like analyze_building_age_price_impact or detect_flips without opening a 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?

Specifies the location requirement ('at least one of code_postal, commune, or code_departement') and the optional type_local filter, plus the reliability guard (<10 transactions → null). It does not name a competing sibling or state when this is preferred over analysis tools that also look at age/price, so it stops short of explicit 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 cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds real behavioral context beyond them: a 5-credit cost per call, the automatic 12-month restriction on radius searches over 1000m, and the summary.basis='sample' vs full-stats distinction. It does not describe the return record shape, but the cost and silent-restriction disclosures are substantive.

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 REQUIRED constraint, then examples, then options, then cost. Structure is excellent and each block is useful, though the examples section repeats filters already enumerated above it, adding some length for a 22-parameter 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 22-parameter, no-output-schema search tool, the description covers the critical calling constraints (location requirement, pagination defaults via schema, summary mode, cost). Return-value shape is only lightly sketched, but the summary_only/full-results contrast covers the main ambiguity.

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 constraints the schema cannot express: no parameter is marked required in the schema yet at least one location filter is mandatory, plus commune formatting quirks (uppercase, 'PARIS 01'–'PARIS 20') and worked filter examples. This meaningfully supplements 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 ('Search French property transactions (Demandes de Valeurs Foncières)') with scope. The DVF reference and location-filter framing make it clearly distinguishable from analytical siblings like analyze_market_statistics or find_property_comparables.

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 the mandatory precondition (at least one location filter) and enumerates the five valid filter combinations. It routes to alternatives in-line, telling the agent when to use summary_only ('for overviews') and how its stats relate to analyze_market_statistics, plus noting the radius_m>1000m date restriction.

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=true and openWorldHint=false, so the description carries the rest and delivers: results are sorted by distance, the optional DVF enrichment covers the last 24 months, and each call costs 5 credits. It does not mention pagination limits beyond 'limit' or failure behavior, keeping it below 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-loads the one-line purpose, then organizes parameters, a chaining tip, an example, and cost under clear labels. It is longer than strictly necessary but nearly every line earns its place; the enum glosses and example are the only mildly verbose stretch.

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 explaining the return shape (businesses within radius, distance-sorted, optionally DVF-enriched) and adds cost, chaining, and a worked example. An agent has everything needed to invoke it correctly and know what comes back.

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 genuine meaning beyond the schema: it expands each enum value with a human-readable gloss (e.g. 'notaire' — notary, 'promoteur' — property developer) and explains why include_dvf_stats matters (competitive intelligence). This is real added value the raw enum list lacks.

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 (Find) plus resource (real estate businesses) and scope (near a location, sourced from the INSEE SIRENE registry). It also names the sibling get_real_estate_business_details as the follow-up tool, so an agent can distinguish this search tool from the detail-lookup 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?

Names an explicit alternative (get_real_estate_business_details with the siren field) and a use case (competitive intelligence via DVF enrichment), and discloses cost (5 credits). It stops short of stating when NOT to use this tool or how it compares to other search-orientated siblings like search_property_transactions.

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=false, idempotentHint=true, and destructiveHint=false, so the mutation profile is covered. The description adds value beyond that: plan gating, cost (0 credits), and the non-destructive pause-via-is_active behavior. It doesn't cover reversibility of field changes or partial-update semantics for the 9 optional 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?

Short, front-loaded, and scannable with a clear REQUIRED marker and a one-line cost note. Minor redundancy: the Pro/Enterprise requirement is stated twice, which costs a little space.

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 safety profile is covered by annotations and there is no output schema to explain, so the essentials are present. However, for an 11-parameter partial-update mutation with 27% schema coverage, the description is thin on how unspecified fields are treated and what the other nine parameters mean, leaving gaps an agent would want filled.

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 only 27% across 11 parameters, so the description carries a heavy burden it largely does not meet. It documents the required id and repeats the is_active pause semantics already present in the schema, but says nothing about prix_min/prix_max, surface bounds, type_local, code_postal, code_departement, or webhook_url replacement behavior.

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 (Update) and resource (existing webhook alert), which cleanly separates it from create_market_alert, delete_market_alert, and list_market_alerts. It does not explicitly name a sibling, but the verb+resource pairing is 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?

Gives real usage context: the Pro/Enterprise plan prerequisite, the required id sourced from list_market_alerts, and the tip to use is_active:false to pause instead of deleting. It stops short of explicit when-not-to-use-this-tool guidance or pointing at update_portfolio_property-style alternatives.

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

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

The annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it specifies which fields invalidate the cached estimate, noting it will be refreshed on the next get_portfolio_property call, and states the credit cost. This exceeds what annotations alone convey, though it doesn't detail permission needs or partial-update semantics.

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 required information, uses clear headings, and efficiently lists optional parameters and the invalidation note without wasteful sentences. Every part serves a purpose.

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 an 11-parameter update tool with annotations covering safety and idempotency, and no output schema, the description provides a complete picture: required vs. optional fields, side effects (cache invalidation), and cost. It could mention whether updates are partial or full-replace, but otherwise is sufficient.

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 meaning by highlighting the required parameter and listing optional ones, and by calling out the invalidation effect for specific fields. However, it doesn't add syntax or format details beyond what the schema provides.

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

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

The description states a clear verb+resource ('Update metadata for a portfolio property') and lists the mutable fields. It doesn't explicitly differentiate from siblings like add_property_to_portfolio or delete_portfolio_property, but the verb 'update' combined with the field list makes the purpose 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 implies usage by naming required and optional parameters, and the note about cache invalidation provides context for when the operation has side effects. However, it doesn't explicitly state when to use this tool versus alternatives (e.g., delete_portfolio_property or add_property_to_portfolio) or any prerequisites beyond the ID requirement.

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