Claro AI by Casafari

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds genuinely new facts beyond them: zero token cost and the presence of an actionable top-up link in the response, both of which affect agent planning.

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 sentence, front-loaded with the resource ('this account's plan'), that spends every clause on a distinct return value. No filler, no restatement 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 present, the description carries the burden of describing returns and does so by enumerating each field of the payload plus the conditional top-up link. For a parameterless, read-only status tool this is fully sufficient 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?

Zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly focuses its words on outputs instead of inventing parameter 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?

Names a specific resource (this account) and enumerates exactly what is reported: plan, remaining Casafari tokens, credits expiring within 30 days, current call eligibility, and a top-up link. None of the sibling tools (all claro_* search/plot tools) overlap with this, so the agent can distinguish it at a glance.

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

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

The closing note 'Free (uses no tokens)' gives an explicit cost-based decision rule and the 'whether calls can be made now' clause implies the diagnostic use case (check before or after hitting limits). It stops short of stating when to call it relative to other operations (e.g. on quota errors), so it is clear context rather than full when/when-not guidance.

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

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

Beyond the readOnly/destructive annotations, it discloses the 10 MB cap, that the file is not stored, that a call costs 100 tokens, and what the response contains (brief, requirements with verbatim quotes, quotes_checked). Those are exactly the operational facts an agent needs before uploading a file.

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?

Dense but front-loaded: what it reads, how it is passed, the limits, then the return shape and next step. The opening clause is slightly convoluted in phrasing, and the format list could be compressed, but nothing is superfluous.

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

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

With no output schema, the description carries the return contract itself and does so (brief, requirements with quotes, quotes_checked), plus size limit, storage behavior, cost and follow-up step. Nothing material is missing for a 3-parameter upload-and-extract 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 that filename is 'best' provided (an encouraged optional) and that media_type should accompany the base64 payload. It still defers concrete media-type values to the schema's own examples rather than repeating 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 ('The premises requirements a file states') and enumerates the accepted file kinds, so an agent can tell it apart from claro_search_premises or claro_get_premises without opening a schema. The closing 'nothing is searched here' pins the scope further.

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

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

Gives an explicit workflow: show the brief to the user, then pass it to claro_search_premises, which names the natural next tool and excludes search from this one. It does not cover the case where requirements already exist as text rather than a file, so there is no stated alternative for that path.

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 destructiveHint=false, so the safety profile is covered. The description adds two things the annotations do not: a per-call cost of 25 tokens and a Free-plan eligibility restriction, both of which materially affect whether an agent should invoke it.

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 sentences, front-loaded with the core action, followed by the eligibility constraint and then the cost. Zero filler; every clause carries a distinct operational fact.

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 never says what a comparison returns (a side-by-side table, prose, or the 'answer' the lang parameter implies), which is a real gap for a tool whose whole value is its output. The Free-plan and cost notes are good, but the item-count error leaves the definition partly unreliable.

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 would be 3, but the description states '2 to 10 premises' while the schema caps ids at maxItems 5. That mismatch actively misleads an agent into passing 6-10 ids that will fail validation, which is worse than adding no parameter detail 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 action (put premises side by side) on a specific resource (premises), scoped to ids returned by a search. It is distinguishable from claro_get_premises (single premise) and claro_search_premises, though it never names those siblings 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?

Gives a clear precondition (ids must come from a prior search) and a plan-based restriction (on Free, only ids your own searches returned). It stops short of naming which sibling to call first or when to prefer claro_get_premises instead.

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 (read-only, non-destructive, closed-world), and the description adds substantial behaviour beyond that: the entitlement requirement, the null-not-zero convention for missing figures, a per-call cost of 25 tokens, and the crucial caveat that the footfall figure is a comparative index, not a head count. That last point prevents a serious misinterpretation an agent would otherwise make.

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 what it returns, then constraints and caveats. The long metric enumeration is dense but each item carries information; the definition is not padded, though the opening sentence is heavy for a single sentence.

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 takes on the burden of describing what comes back and does so thoroughly — footfall splits, resident age bands, income bands, and amenity categories — plus cost, entitlement, and null handling. An agent has everything needed to call it and interpret the result 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 schema already explains id vs lat/lon and the lang enum in detail. The description only restates the id-or-point choice without adding format or constraint detail, so it sits at the baseline for a fully documented 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: location intelligence metrics (footfall index, resident demographics, nearby amenities) for a premises id or a lat/lon point in Spain. The enumerated metric families make it clearly distinct from siblings like claro_get_premises or claro_compare_premises.

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?

Makes the input choice explicit (a premises id, or a point via lat/lon) and states a hard prerequisite: the organisation's plan must include Location Intelligence. It does not explicitly name sibling alternatives or when to prefer claro_compare_premises for multi-site comparison, which keeps it 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 already declare readOnlyHint, destructiveHint false and closed-world, so safety is covered; the description earns credit on top by disclosing the 25-token cost per call and the Free-plan restriction on which ids are fetchable. It does not mention failure behaviour for unknown or expired ids, which would matter for a metered 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?

Two sentences, front-loaded with the core action and the id provenance before the return inventory. Every clause carries information — the long enumeration is justified because no output schema exists to describe the response.

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

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

With no output schema, the description carries the return-value burden and does so by listing each field class including the per-fact source quotes. Combined with cost and plan limits, an agent has everything needed to decide and call correctly; the lang semantics live in 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% and the id parameter already documents its pm_... format and search provenance, so the schema does the heavy lifting and the baseline applies. The description reinforces the id's origin but says nothing about the lang parameter or how language selection affects the returned facts and quotes, adding no meaning beyond the schema.

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

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

"One plot in full by the id ... returned" names a specific verb-and-resource pair and then enumerates exactly what comes back (data, commercial-use level, quoted facts, excerpt, agency link, competing agencies). It explicitly ties itself to claro_search_plots, so an agent can separate it from search or premises siblings 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?

The description establishes the prerequisite chain clearly: this is the follow-up to claro_search_plots, called with an id that search produced, and on the Free plan only ids your own searches returned are legal. It stops short of naming an alternative for lookups outside that chain or stating what to do when the id is stale, so it is strong context rather than a full when/when-not rule set.

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

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

Annotations already declare readOnlyHint and non-destructive behavior, so the description adds value by disclosing a hard cost (25 tokens per call) and a Free-plan eligibility constraint. It also explains that insights gates charts and that assessment requires insights and may wait on a model call, though the caching detail itself lives mostly in the schema text.

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?

It is a single dense block but front-loaded: the core action and return contents come first, then the optional enhancements, then plan and cost constraints. A few clauses are long, yet every sentence carries operational information rather than 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 carries the burden of describing the return payload and does so thoroughly, enumerating data, facts, photos, timeline, market status, ad links, charts and the optional assessment. An agent can decide whether to spend the tokens knowing what it will receive.

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

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

Schema coverage is 80%, so most parameters are already documented. The description still adds meaning beyond the schema by spelling out what the insights charts contain and the dependency that assessment only produces a site assessment when insights is set, which is more than the bare schema default conveys.

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 and resource ("One premises in full by the id a search returned") and then enumerates exactly what comes back: data, extracted facts with source sentences, coordinates, up to 8 photos, asking-price timeline, market status and agency ad links. This clearly distinguishes it from siblings like claro_search_premises and claro_compare_premises.

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

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

It states the prerequisite that the id must come from a search result, and gives a plan-level restriction ("On the Free plan, only for ids your searches returned") plus the token cost. It does not explicitly route the agent away from claro_compare_premises for multi-premises comparison, which keeps it 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 already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real context beyond them: the figures are asking prices rather than agreed/transaction prices, cohorts below 10 listings produce no figures at all, and each call costs 25 tokens — the last being operationally important for an agent. It does not describe ordering, pagination, or result 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?

The opening sentence is a long run-on packing five separate output dimensions into one clause chain, which makes it harder to scan than it needs to be. The three following sentences (input modes, price caveat, minimum cohort, cost) are tight and each earns its place, so the waste is in structure rather than content.

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

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

There is no output schema, so the description must carry return-value semantics, and it does: distribution with median and middle half, segmentation by size band and district/town, a three-year monthly series with annual change, and listing counts with days on market. Against a 50+ field criteria object it is still thin on how criteria combine and on ordering of results, but the core shape is conveyed.

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

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

Schema description coverage is 100% across a very large nested criteria object, so the schema does the heavy lifting and baseline 3 applies. The description does add one genuinely useful semantic point — that the same request can be expressed as free-text question or as structured criteria data — which explains the relationship between the two top-level inputs.

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

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

The description names a specific resource and computation: asking price per m² as a distribution with median and middle half, by size band and by district or town, plus a three-year monthly average with year-on-year change and days on market. That is far more precise than the title 'What premises ask in a place'. It does not explicitly point at the sibling it is not (claro_search_premises for individual listings, claro_compare_premises for comparisons), so the differentiation is inferable rather than stated.

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 the framing — this is the tool for 'what do premises of this kind ask here' market questions — and the minimum-10-listings rule tells the agent when results will be suppressed. However there is no explicit when-to-use versus claro_search_premises or claro_compare_premises, and no statement of what this tool is not for.

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 annotations: searches persist for 24 hours, each call and each page counts against the Free plan's 4 searches, and each call costs 100 tokens. It also explains that results match claro_search_premises and that next_cursor pages through results.

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

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

The purpose and operational constraints are front-loaded and easy to scan. There is minor redundancy around calls and pages counting as searches, but the paragraph remains compact and useful.

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 9-parameter search-refinement tool with no output schema, the description covers the missing pieces an agent needs: source of search_id, pagination behavior, retention, quota impact, token cost, and return-shape reference to claro_search_premises.

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 high, so the schema already documents most parameters. The description still adds useful meaning for the key change parameter with concrete plain-language examples, and reinforces the search_id retention and cursor pagination semantics.

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

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

States a specific action: change part of an earlier search and rerun it as a new search with its own search_id and pages. This clearly distinguishes it from claro_search_premises, the initial search tool.

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 take search_id from claro_search_premises, gives plain-language examples for change, and explains cursor pagination. It also clarifies when cursor requires no change/brief/criteria, leaving little ambiguity about when to use this tool versus 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 a safe read-only, closed-world operation, and the description adds real value beyond them: deduplication across agencies, token cost per call, plan-based limit capping, and the rule that each page counts as a separate call and search. Result format is not described, but no output schema exists to cover it either.

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 what the tool returns and the dedup guarantee, then criteria, then the cost/quota rules. The criteria list is dense but mirrors the nested schema compactly; no filler sentences.

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 tool with a nested criteria object, zero required parameters, and no output schema, the description covers cost, quota, pagination, deduplication and the semantics of the trickiest filter. It omits what a result looks like, which is the main remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: commercial_use is glossed as how far the property's own text says a commercial building can go, and limit is described as capped by the plan rather than only by the schema maximum of 50.

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 ("Find plots of land for sale or rent in Germany for a commercial building") and adds a distinguishing behavioral fact: one result per plot regardless of how many agencies advertise it. This differentiates it cleanly from the premises-oriented siblings without needing to name them.

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

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

Gives useful operational guidance about paging (limit/offset, each page is a call) and the Free plan's 4-search allowance, which shapes how an agent should call it. However, it never says when to prefer this over claro_search_premises, claro_refine_search, or claro_get_plot, so tool selection 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?

Annotations already declare readOnly/destructive=false, but the description adds genuinely non-obvious behavior: per-call token cost, the Free-plan search budget where every page is a call, the 200-result page cap being plan-dependent, and that check adds seconds and switches off above 50 results. It also discloses what a result entry contains and how Location Intelligence changes the payload, which no annotation 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?

It is a single dense paragraph, front-loaded with purpose, then the return shape, then paging, then cost and exclusions. Every clause carries information, but the long enumeration of return fields reads as a run-on and would be easier to scan as separate lines.

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 top-level parameters, a deeply nested criteria object and no output schema, the description carries the right load: it explains the answer's structure, the paging model, cost, and the excluded use case. The only residual gap is the unmentioned Germany/Portugal support, which the country parameter documents anyway.

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, and the description earns an extra point by explaining the brief/criteria interaction that the schema never states ("Describe the site in plain words in any language... criteria override the brief") and the cursor/search_id continuation semantics. It stops short of interpreting the more subtle criteria fields (sort, meaning, supply_gap), leaving those entirely to the schema.

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

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

The opening sentence gives a concrete verb and resource ("Find shops, restaurant premises, offices, warehouses... for rent or sale") and explicitly excludes homes, naming the alternative: "apartments, houses and other homes are Property Sourcing (property-sourcing_search)". The only defect is the scope claim "anywhere in Spain", which conflicts with the schema's country enum (es, de, pt) and understates coverage.

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

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

It states the negative case (never for homes) with the named sibling to use instead, explains the two input modes and their precedence ("criteria override the brief"), and gives the continuation protocol ("send next_cursor as cursor", "Keep search_id to refine"). Cost and quota context (100 tokens a call, 4 searches on Free, each page counts) further tells the agent when a call is affordable.

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