us-property-parcel-real-estate-debt

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

Annotations already signal read-only, idempotent, and non-destructive behavior. The description goes further by disclosing cursor mechanics, learning-time ordering, determinism, indexed performance, and cost ('Free'). It does not specify the response item shape or deletion behavior, but it adds solid context beyond the annotations.

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

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

Four tightly written sentences, each earning its place: what the tool returns, ordering semantics, cursor protocol, filters, and cost/performance. The most important information is front-loaded.

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 description covers purpose, ordering, cursor workflow, filtering, and cost, which is sufficient for a read-only polling tool with no required parameters. The only notable gap is the absence of any description of the result payload shape or whether deleted entities appear, especially since there is no 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?

With only 60% schema description coverage, the description compensates well by identifying that event_type, state, and place_dfx_id act as filters and by explaining the cursor's role. It does not clarify limit's behavior, but schema default of 50 plus the overall usage narrative make it reasonably inferable.

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 clearly identifies the operation ('Poll for what is NEW to you') and the resource (DFX's learned state since a cursor). The phrase 'ordered by when DFX learned it rather than by when it happened' conceptually separates it from event-time search, though it does not explicitly name a sibling 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?

It gives a concrete call pattern: call with no cursor to establish a starting position, then call again with the returned cursor to get everything new in between. It also enumerates useful filters. It stops short of saying when not to use this tool or naming alternatives, but the intended usage is clear.

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/destructive safety; the description adds the crucial billing side effect ('charged once and served in the same response'), the no-charge quote path, and the data-quality guarantee ('19,881 of 19,881 loans... none estimated'). This context is essential for an agent deciding whether to invoke a paid tool.

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 long but front-loaded: billing and quote behavior come first, then return shape, data quality, and the free alternative. A few phrases repeat the title or echo the schema, but the length is justified by the payment workflow.

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 paid tool with no output schema, the description covers the safe call sequence, what data arrives, the confirmation guarantee, row limit, ordering, and the free fallback. Nothing an agent needs to correctly invoke it 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?

The schema already documents all four parameters at 100% coverage, so the baseline is 3. The description still adds operational meaning beyond the schema: 'without authorize' produces a quote, 'with authorize' charges once and serves, and the limit does not affect the price. State is also tied to per-state pricing.

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 is explicit: 'Returns the LOAN rather than the event' for one US state and a forward window, listing exact fields, deduplication, and ordering. This clearly distinguishes it from the sibling search_property_events and pins the resource and behavior precisely.

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 precise free alternative and when to use it: search_property_events with event_type=LOAN_MATURITY_SCHEDULED returns up to 50 events with less data. It also scripts the paid call flow: omit authorize for a quote, send authorize plus header to be charged and served in one response.

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 mark the tool as read-only, non-destructive, and idempotent. The description adds useful behavioral context beyond that: it reports known gaps, geography limitations (single state), and the absence of calibrated probabilities. No contradiction with 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?

Two tightly packed sentences convey purpose, coverage, limitations, and a usage heuristic without fluff. The key caveats are stated plainly and the actionable instruction is placed at the end for emphasis.

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 zero-parameter, read-only, idempotent tool, the description fully covers what the agent needs: what data is returned, what caveats exist, and when to call it. The lack of an output schema is mitigated by the explicit list of report contents.

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 has zero parameters, so the schema provides no meaningful semantics. The description compensates by indicating what the returned report covers, which is sufficient for parameter-less invocation.

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 clearly define the resource: DFX's measured coverage, served sources, object types, and known gaps. It is differentiated from siblings like what_can_dfx_answer by focusing on coverage limitations rather than question-answering capability.

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 gives an explicit call-to-action: invoke this before concluding an empty result means an absent market. It does not name alternative tools, but it provides a clear decision context, which is enough for a zero-parameter informational tool.

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

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

Annotations already cover read-only, idempotent, non-destructive safety, so the description adds value with the sales semantics: it explicitly warns that sales carry BOTH the instrument total and the parcel's allocated share because a deed repeats its full price. The 'Free.' note also adds cost behavior beyond the annotations.

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

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

The description is dense but every sentence earns its place: it states the input source, enumerates the return categories, explains an important data nuance, and signals cost. The structure front-loads the core behavior before the clarifying detail about sales consideration.

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 explaining return content, and it does so thoroughly by listing current state, events, ownership, management, debt, sales, and provenance. Minor omissions like pagination or not-found behavior are acceptable given the single required parameter and read-only annotations.

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 input schema already fully describes dfx_id as 'id returned by resolve_address,' and the description repeats the same constraint without adding new format, validation, or usage details. With 100% schema description coverage, the description provides no additional parameter meaning beyond the 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?

The description names a specific verb and resource: given a DFX id, return a comprehensive property record. It distinguishes this tool from siblings by noting it starts from resolve_address output and returns 'everything DFX holds,' which clearly separates it from search_parcels, changes_since, and debt_maturity_schedule.

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 phrase 'Given a DFX id from resolve_address' provides clear usage context: this tool is called after address resolution, not before. It does not explicitly name alternatives or exclusions, but the 'everything DFX holds' framing implies when the full record is needed rather than a narrower sibling tool.

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

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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond that: addresses may return a property, a parcel, or both, because these are 'separate populations that barely overlap,' and ambiguity is explicitly stated. This meaningfully informs the agent's expectations.

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 three focused sentences with the core action front-loaded. Each sentence earns its place, though 'Free' is a minor extra that is useful but not essential. Overall it is tight and scannable.

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

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

With no output schema, the description does a decent job explaining return categories and ambiguity, and annotations cover the safety profile. However, it omits behavior for no matches, does not clarify how limit applies, and leaves city/state usage to inference. This is adequate but has clear gaps.

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 only 50%, and the description does not compensate for the undocumented city and limit parameters. It restates address-level intent but adds no meaning for the optional parameters or limits. The schema covers address and state, but gaps remain for city and limit.

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 verb and resource: turning a street address into canonical DFX object ids, and specifies the output types ('property' and/or 'parcel'). This clearly distinguishes it from siblings like resolve_organization and search_parcels without requiring schema inspection.

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?

'Start here, then call get_property_record with an id' gives explicit workflow context and positions this as the entry-point lookup. It does not explicitly state when to prefer search_parcels or when not to use this tool, but the 'start here' guidance makes the intended usage clear.

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

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

Annotations already cover read-only and non-destructive behavior. The description adds valuable behavioral nuance: a name is treated as a blocking key, not an identity, and all candidates are returned rather than a single guess. It also mentions the service is free, which is beyond what annotations 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?

The description is three short sentences with no filler. The core action is front-loaded, followed by the key matching behavior and the important person-lookup exclusion. Every sentence adds distinct value.

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, idempotent resolver with two parameters, the description is mostly complete: it explains what inputs are expected, what the output represents, and the main exclusion. The main gap is the undocumented limit parameter and how it interacts with the 'all candidates' behavior, but overall this is sufficient for an agent 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 0%, so the description must carry the parameter-meaning burden. It explains the semantic role of 'name' well (company or role-holder names, blocking key). However, it does not clarify the 'limit' parameter at all, and the claim about returning all candidates sits awkwardly with the default limit of 10.

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 clearly states the tool's function: it turns an owner, manager, lender, or servicer name into canonical DFX entity IDs. It also distinguishes itself from person lookup by explicitly saying that is not offered, which helps disambiguate from sibling resolvers.

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 gives clear context for when to use the tool: resolving organization-related role names to DFX entity IDs. It also states a when-not case (person lookup is not offered), though it does not name a specific alternative tool such as resolve_address.

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 and idempotent annotations, the description discloses meaningful response behavior: 'Every answer states the true match count alongside the sample,' and a no-match search 'names the filter that emptied it rather than returning a bare empty list.' It also describes the fields carried in results, adding context that annotations do not provide.

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 the core action and resource, then enumerates filters and result fields, and finishes with edge-case behavior and the filter requirement. Every sentence contributes distinct information with no redundant 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?

Given the rich input schema, the sibling context, and the absence of an output schema, the description adequately covers what the agent needs: filterable fields, returned fields, match-count behavior, no-match naming, required filter rule, and cost. No significant operational gap remains.

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 high at 90%, so most parameter meanings already live in the schema. The description adds the crucial constraint 'At least one filter is required,' which is not evident from the schema's zero required parameters, and it lists the filterable dimensions, reinforcing the parameter 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?

The description opens with a specific verb and resource: 'Search the assessor parcel layer with filters instead of one exact address.' It distinguishes itself from resolve_address and clarifies the unique question-answering role of the tool, so an agent can clearly identify its purpose among siblings.

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

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

The description explicitly states when to use this tool: 'This is the only way to ask a QUESTION of the parcel layer: resolve_address needs an address you already have.' It also gives a concrete usage rule, 'At least one filter is required,' and notes the tool is 'Free,' disambiguating the choice context clearly.

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 mark the operation as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: unrecognized event types are refused with the served vocabulary rather than returning empty results, and the data is described as free with provenance and a user-presentable headline. This exceeds annotation coverage without contradicting 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?

The description is dense but purposeful: it front-loads the general purpose, then gives coverage specifics, volume statistics, filtering dimensions, and refusal behavior. The long enumeration of event types and counts earns its place because it clarifies scope, though it could be tightened without losing key 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?

Given the absence of an output schema, the description usefully mentions that results include provenance and a headline. It also communicates geographic limitations, date anchoring, and closed-world refusal behavior. Missing details like pagination or limit semantics are minor because the operation is read-only and the calling pattern is straightforward.

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 only 25% (only state is documented), so the description must compensate. It adds meaning for event_type by translating enum values into understandable categories and mentions state and days-ahead filtering, but it does not address the limit parameter or provide precise value formats beyond what the schema states.

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 clearly identifies the tool as a search over dated property/parcel events and enumerates the specific event domains it covers. It is more specific than the title and gives a concrete sense of scope, though it does not explicitly contrast itself with sibling search 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 explicitly lists what event categories are covered, along with geographic and temporal scope, and states that filtering is by event type, state, and days ahead. It does not name sibling alternatives or say when not to use it, but the coverage details provide clear context for when this tool applies.

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 description says the tool 'records what was asked so unmet demand shapes what DFX builds next,' implying a write/logging side effect, while annotations declare readOnlyHint=true and idempotentHint=true. Recording on each call would not be idempotent either. This is an annotation contradiction, capping the score at 1.

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, all informative: core capability, no-answer/recording behavior, and usage trigger. Front-loaded with what the tool returns, with no filler or repetition.

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 description covers the return contract (yes/no, tool, arguments, sample) and the no-case, which matters because there is no output schema. However, the `constraints` parameter is completely undocumented, and the description does not explain how constraints influence routing or sampling. It is a usable minimal definition, but not fully complete for safe 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?

Schema description coverage is 0%, so the description must define parameters. It gives meaning to `objective` via 'Describe an objective in natural language,' but never mentions `constraints`, an optional object with no property schema, leaving agents to guess what constraints can contain.

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

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

States a concrete verb ('Describe an objective... and get back whether DFX can help'), names the resource (DFX's capabilities), and describes the output (which tool to call, arguments, sample result). The closing 'Call this first if you do not know what to ask for' clearly distinguishes it from the domain-specific sibling tools as the meta-routing entry point.

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 'Call this first if you do not know what to ask for,' giving a clear trigger condition. It does not, however, name sibling tools or state explicit exclusions for when a known domain tool should be used directly.

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