flatin.pt — Portuguese property taxes

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description's additional clarification that VPT is the tax authority's valuation rather than the purchase price is useful. But it does not disclose return format, rate-source assumptions, or error cases; with the safety profile covered by annotations, this is adequate but not rich.

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 two front-loaded sentences with no fluff: the first defines scope and calculation, the second prevents a common input mistake. It loses a point only because the VPT clarification partially repeats the schema's 'Not the purchase price' note.

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

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

For a two-parameter calculation with strong annotations, the description covers the main inputs, the property type, the single-municipality limit, and the VPT-vs-price trap. It does not state the return value's format or currency, but 'yearly IMI' makes that largely inferable; no output schema exists, so a bit more return clarity would make it fully 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 description coverage is 100%, so the baseline is 3. The description reinforces that 'vpt' is not the purchase price and tells the agent to ask the user for it, adding slight value, but it offers no format/range details for either parameter that the schema doesn't already provide.

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

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

The description states a specific verb and resource: 'Yearly IMI for an urban property' from a taxable value (VPT) at the municipality's urban rate. It clearly identifies the calculation target and scope, but does not explicitly reference sibling tools such as imi_rate or imt_calculate, so differentiation relies on the agent recognizing 'yearly IMI' vs the other tax tools.

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

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

It conveys clear contextual guidance: the tool is for one municipality's urban property and the user should provide VPT rather than the purchase price. However, it never states when to prefer this tool over siblings, nor gives exclusions (e.g., rural properties or multi-municipality cases), leaving when-to-use vs alternatives 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 readOnly/idempotent/non-destructive behavior, so the bar is lower. The description adds valuable context: the data source (Autoridade Tributária), quality assurance across all 308 municipalities, and the important behavior of explaining per-parish rates instead of returning zero.

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 sentences, with the core purpose first, followed by data provenance and a key edge-case caveat. Every sentence adds distinct value and there is no filler.

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

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

For a single-parameter lookup whose safety profile is fully covered by annotations, the description is nearly complete. It explains accepted inputs and the main exception, though the absence of an output schema means the exact response format is slightly under-specified.

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

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

The schema already describes the single parameter at 100% coverage, so the baseline is 3. The description adds concrete accepted formats and examples (Portuguese name or four-digit code), which meaningfully clarifies how to supply the municipality value.

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?

Title and description name a specific verb ('Look up') and resource ('IMI rate of a municipality'), with the input forms (name or four-digit code) made explicit. This clearly distinguishes it from the sibling cost/calculation tools.

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

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

The description makes clear what the tool does and when its edge case applies, but it never explicitly tells the agent when to prefer this over imi_annual_cost or imt_calculate. Usage is implied rather than directly guided.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the burden is light. The description adds real value beyond them: output is in cents and formatted euros, tables are official 2026, and it discloses the reduced-table and stamp-duty-deduction logic and the higher-of-price-or-VPT charging rule.

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 scope and cost components, then the operative parameter rule, then the return format. Dense and largely waste-free, though the two long sentences pack several distinct facts together.

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 states the return shape (cents plus formatted euros, plus table sources) and the key tax computation rule. Complete enough to invoke correctly for a read-only calculator; only sibling routing guidance is thin.

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

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

Schema coverage is 100%, so the schema already documents value, vpt, territory, primary_home and buyer_is_young in detail. The description restates the vpt rule and the age-35 condition without adding syntax or edge-case meaning beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (calculate) and resources (IMT, Imposto do Selo, registration price) scoped to a Portuguese home purchase. This distinguishes it cleanly from imi_annual_cost and imi_rate, which cover recurring property tax rather than transaction taxes.

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 by 'what buying a home in Portugal costs on top of the price' and it gives one concrete rule (pass vpt when known), but it never states when to prefer this over the sibling tax tools or what its boundaries are. Adequate context, no explicit alternatives or 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 signal read-only, idempotent, non-destructive behavior; the description adds the key behavioral fact that the request is submitted by the person, not on their behalf. This prevents an agent from assuming the tool performs the consultation submission itself.

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?

A single front-loaded sentence covers purpose, output, language handling, and the non-submission caveat. There is no redundant filler or repetition of the title beyond what is necessary.

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

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

For a low-complexity tool with one optional parameter and no output schema, the description names the returned artifacts (form link, consent text) and the critical behavioral caveat. It could mention the link format, but nothing essential is missing for correct invocation.

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

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

The only parameter, language, is fully described in the schema with its allowed values, default, and meaning. The description's 'in the user's language' echoes that schema rather than adding new semantic detail.

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 ('returns') and resource (consultation form link + RGPD consent text), and frames the tool's role as connecting the user to a licensed Portuguese real estate agency. This clearly separates it from the sibling tax/rate calculators even without naming them.

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

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

The opening 'How to put the user in touch with a licensed real estate agency in Portugal' gives a clear context for when to invoke the tool. It does not explicitly list exclusions or alternative tools, but the purpose statement is enough to route an agent correctly.

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