DFX Real Estate Intelligence

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

Annotations already mark it readOnly, idempotent, and non-destructive, and the description adds substantial context beyond that: two calls required, first returns zero by design, ordering is by learned time, deterministic/indexed/cheap, and historical families flow through. Nothing contradicts 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 longer than average but every section adds necessary context: polling protocol, alternative, filters, cost/performance, and historical behavior. The key rule is front-loaded. There is some repetition of the learned-time ordering point, but it is used deliberately to emphasize the historical delta behavior.

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 cursor-based polling tool with no output schema, the description covers all critical operational details: how to start, what the first call returns, what the second returns, what filters are available, cost characteristics, and how it differs from search_property_events. An agent has enough to call it correctly without further inference.

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 high, and the description reinforces filter semantics by naming event type, state, and property/parcel ID. It also clarifies the cursor behavior in plain language ('with no cursor...second, with that cursor'). It adds value beyond the schema even though it doesn't detail every parameter.

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: 'Poll for what is NEW to you' and defines the unique ordering principle ('when DFX learned it rather than by when it happened'). It also distinguishes itself from search_property_events, so an agent can immediately tell what this tool is for without inspecting 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?

It gives explicit when-to-use guidance, including the exact two-call cursor protocol and the alternative: 'If you want rows now rather than a subscription, call search_property_events instead.' It also explains what must not be used for past-dated facts via within_days, which makes the boundary 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?

Even though annotations already declare readOnlyHint=true and idempotentHint=true, the description adds substantial behavioral context: the tool is the only priced/credentialed one on the server, a quote call is free and unrefused, and a charged call requires an identical request with authorization. It also discloses that results are deduplicated, ordered by maturity, and that every maturity_basis is confirmed with no estimated or inferred dates. This far exceeds the annotation baseline and provides rich behavior around the payment flow.

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 longer than average, but the length is justified by the novel paid-quote-authorize handshake that must be explained precisely. It is front-loaded with pricing and the tool's core distinction, then moves through output details, quote behavior, charged behavior, and the free alternative in logical order. There is minor repetition of the 'only priced/credentialed tool' theme, which keeps it from a perfect 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?

This is a high-complexity tool with no output schema, and the description carries that burden well: it lists every returned field, the row limit, ordering, deduplication, data-confidence guarantees, the quote/charge sequence, required headers, account setup, and the free sibling alternative. An agent reading this description alone knows exactly how to call the tool, how to avoid charges, how to authorize a charge, and what results to expect.

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, and this description adds real value beyond it. It explains the semantics of the authorize flow at length, including the quote_id from the PAYMENT_REQUIRED reply and the max_price_usd ceiling checked before charging. It also clarifies that the price is per state and does not change with row count, which is meaningful parameter context not present in 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 description opens with a clear verb and resource: it 'Returns the LOAN rather than the event' for confirmed commercial mortgage maturities per US state and forward window. It enumerates the exact returned fields and explicitly differentiates itself from the sibling search_property_events, which returns maturity events. The title and first line also establish that it is the paid tool, so there is no ambiguity about its scope.

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 explicit when-to-use guidance: use this tool 'for a refinancing conversation' and use the free alternative search_property_events 'for timing.' It also provides a complete usage path: call without authorize for a free quote, then resend with authorize and an X-DFX-Account header to be charged. It even routes the user to open_dfx_account to obtain a credential, which is exactly the kind of conditional guidance an agent needs.

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 goes well beyond the annotations by disclosing that the tool queries no data, that verdicts come from a coverage registry, and that NOT_COVERED is measured rather than inferred from empty search. It also discloses limitations such as single-state geography and lack of calibrated probability. This is valuable behavior an agent could not infer from 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 description is dense but each sentence adds a distinct point: what it reports, when to call it, how to call it with no arguments, how to call it with filters, and why the result is trustworthy. It is slightly longer than strictly necessary but front-loads the key purpose and usage guidance.

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?

This tool has zero required parameters and no output schema, so the description carries a high burden. It fully covers what the tool returns (full grid vs. one-slice verdict), the set of possible verdicts, the source of truth, and limitations. Nothing an agent needs to correctly invoke and 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 already describes both parameters with 100% coverage, so the baseline is 3. The description adds meaning by explaining the no-argument mode, the state/event_type narrowing mode, and the output shape (COVERED, NOT_COVERED, or UNKNOWN) for those parameters. It also ties event_type to the same vocabulary as search_property_events, which helps the agent reuse known values consistently.

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 a specific resource ('coverage registry') and what the tool does: reports measured coverage and known gaps. It distinguishes itself from event search by explicitly warning not to conclude an empty result means an absent market, and by referencing the same event_type vocabulary as search_property_events.

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 explicit when-to-use guidance: 'Call this before concluding that an empty result means an absent market.' It also tells the agent exactly how to invoke it differently depending on need: no arguments for the full grid, or state/event_type for a direct verdict.

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 idempotentHint=true, so the read-only nature is covered. The description goes beyond that by disclosing the underlying verification mechanism (Strype signature verified and re-read from api.server.com), the meaning of the two statuses, and that it is free. This is rich behavioral context for a read 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?

Four sentences, all relevant, with the core action and scope front-loaded. The 'Free.' fragment and the trustworhy explanation earn their place, though the description is slightly longer than strictly necessary. No redundancy or 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 simple two-param read with annotations and no output schema, the description covers the essential invocation context, the meaning of the status values, and the follow-up action for PAID. It doesn't describe error handling for unknown quote_id or other possible statuses, which is a minor gap given the simplicity.

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 50%: account_key has a schema description, but quote_id does not. The description's 'for one quote' gives minimal context that quote_id identifies the quote, but it doesn't explain the format, that it's required, or how to obtain it. The description partially compensates for the missing quote_id schema coverage but doesn't fully close the gap.

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, 'Reads the DFX payment ledger for one quote,' states a specific verb and resource, and the description clarifies the core question it answers: 'did my payment go through'. It does not explicitly name sibling tools like dfx_coverage or fund_dfx_account as differentiators, so it misses full sibling distinction, but the 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 phrase 'It is the ONLY trustworthy answer to did my payment go through' gives an explicit when-to-use directive. It also excludes alternatives ('A browser redirect, a Stripe success page and a client's own belief are all not receipts') and provides action guidance based on statuses: 'AWAITING_PAYMENT means keep polling. PAID means ... repeat the paid call with authorize.'

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 minimal annotations, it discloses several non-obvious behaviors: the amount is read server-side from the quote, no price parameter exists, card authorization is still required, the success page is not a receipt, and only Stripe TEST payments are collected. This materially reduces the chance of an agent misusing the 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 front-loaded with the core purpose, then adds critical caveats in a logical order: amount authority, card authorization, receipt semantics, and test mode. Every sentence earns its place; the length is justified by the risk of a payment tool.

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

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

With no output schema, the description appropriately states the return values: hosted payment URL and payment id. It also covers test-mode behavior and the polling follow-up, so an agent has enough to invoke and continue the flow. It does not describe failure modes, but those are less critical for a 2-parameter tool with this much context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining that quote_id determines the amount server-side and that there is no price-adjustment field, which prevents the agent from looking for an amount parameter. The account_key fallback context is already present in the schema, so the description does not need to repeat it.

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 names the exact action, resource, and result: open a Stripe payment for exactly one quote and return a hosted payment URL plus a payment id. It distinguishes itself from the sibling dfx_payment_status, which is for polling status, and open_dfx_account, which is for account creation.

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 clearly says to use this tool for one quote and explicitly directs the agent to poll dfx_payment_status until PAID, covering the main alternative. It does not enumerate when-not-to-use conditions for other siblings, but the scope is precise enough for correct 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 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 are all false and offer no safety signals, so the description carries the full burden. It discloses the one-time return of the account key, that DFX stores only a digest and cannot show it again, that the account starts at $0, and that no argument can propose a balance. It also clearly states the mutating nature and the absence of idempotency expectations. 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?

The description is lengthy but every sentence earns its place: critical warnings (one-time key, zero balance, no balance arguments) are front-loaded, and the usage condition is stated in a separate, clear paragraph. The structure makes the essential information easy to parse.

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

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

With no output schema and non-informative annotations, this description is remarkably complete. It covers what the tool does, why it exists, critical storage requirements, the zero-balance invariant, the inability to manipulate balances, and exactly when to use it versus alternatives. No significant gap remains for an agent deciding whether and how to call it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it explains 'quote_id' in the context of a follow-up funding call, and clarifies 'principal' as the party whose money is spent, explicitly excluding software names like 'Claude Desktop.' Label is not expanded, but overall the description elevates parameter understanding.

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: 'Creates an economic identity you control, with NO money in it.' It clearly distinguishes itself from siblings by emphasizing that this account starts at $0 and is required only for paid capabilities, while free sibling tools are unauthenticated and permanent.

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 says 'Call this only if you intend to buy a paid capability' and enumerates that every other discovery, coverage, resolution, property record, and event search tool is free and does not need an account. This gives an agent clear when-to-call and when-not-to-call guidance, exceeding typical alternative 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 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 declare read-only, non-destructive, and idempotent behavior, and the description adds substantial behavioral context beyond that: it reveals the refusal behavior for unrecognized event types ('REFUSED with the served vocabulary, never answered with an empty list'), the forward-only semantics of within_days, and the risk of empty results reading like an absent market. It also tells the caller the response includes provenance and a person-facing headline. This is exactly the kind of behavior an agent needs to know.

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: scope, coverage counts, geographic limitations, time-window semantics, refusal behavior, and cost. It is front-loaded with the most important single-sentence summary, then layers evidence and caveats. The longer length is justified by the breadth of specific, decision-relevant information.

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

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

For a read-only search tool with no output schema, the description covers the essential operational surface: what events are included, which geographies, how time windows work, what happens on invalid event types, and what the response contains (provenance and a headline). The input schema covers defaults and ordering, so nothing critical is left to guesswork. The absence of an output schema is compensated by the explicit return-shape hint.

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 at 75%, so the baseline is already decent. The description adds real meaning beyond the schema by mapping natural-language categories to specific event types (LIHTC compliance period endings, HUD subsidy expiries, CMBS foreclosures, Boston permits) and by clarifying that event_type sends an unrecognized value to a refusal rather than an empty result. It also reinforces the forward-only meaning of within_days with concrete guidance on when to omit it.

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: 'Find dated property events over US properties and parcels.' It then enumerates concrete event families (LIHTC compliance endings, HUD expiries, loan maturities, CMBS distress, permits, sales), which distinguishes this tool from generic search siblings without needing to open the schema. The title and first sentence together make the tool's job unmistakable.

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 strong contextual usage guidance: it scopes coverage explicitly ('Boston only', '2 states', 'now national rather than Massachusetts'), and it gives a detailed warning about when to omit within_days for backward-looking questions. It does not explicitly name sibling tools or state 'use X instead of Y', so it lacks a direct alternative-selection statement, but the coverage boundaries provide a clear context for appropriate use.

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.