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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses key behavioral traits: the ordering by 'when DFX LEARNED a fact' vs. when it happened, the deterministic and indexed nature ('cheap to call often'), the first-call returning zero events by design, and the cursor semantics with the 'complete: false' envelope. It also states that it is 'Free' and explains the historical-family flow explicitly. This goes well beyond the annotations and fully informs an agent of the tool's runtime behavior.

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

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

The description is dense but well-organized: the first paragraph delivers the core purpose, protocol, alternative, filters, and performance characteristics; the second paragraph addresses the important historical-family edge case. Every sentence carries needed information without fluff. The use of capitalization and explicit warnings (e.g., 'TWO CALLS ARE REQUIRED') make critical points stand out despite the length.

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

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

Given the tool's polling/cursor-based nature and the absence of an output schema, the description is remarkably complete. It explains the two-call flow, the cursor's meaning, the envelope's 'complete: false' flag, the filtering options (event_type, state, place_dfx_id), the relationship to search_property_events, and the historical-family coverage. It even clarifies that the event_type vocabulary matches search_property_events. This provides all necessary context for correct invocation and interpretation of responses.

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 has detailed descriptions for all 5 parameters (100% coverage), so the baseline is 3. The description adds extra meaning by explaining the two-call protocol in plain language and clarifying the limit parameter's effect on the envelope and cursor handling ('A full page sets complete: false... go again immediately with the returned cursor'). This supplements the schema descriptions meaningfully, justifying a 4.

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 the tool's purpose with precision: 'Poll for what is NEW to you, ordered by when DFX learned it rather than by when it happened.' It also clearly distinguishes it from the sibling tool search_property_events by noting the alternative for immediate rows. The first paragraph explicitly establishes the core behavior and the two-call protocol, leaving no ambiguity about what the tool does.

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 direct usage guidance by specifying when to use this tool versus the alternative: 'If you want rows now rather than a subscription, call search_property_events instead.' It also explains the required two-call sequence ('TWO CALLS ARE REQUIRED BEFORE YOU SEE ANYTHING') and highlights the historical-family advantage: 'within_days on search_property_events cannot reach the past... a foreclosure that occurred months ago and was ingested today arrives in today's delta.' This is explicit, actionable guidance for an agent deciding between tools.

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

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

Goes well beyond the annotations: it discloses the payment/credential requirement as the only priced tool on the server, explains that quoting never charges, that the max_price_usd ceiling is checked before charging ('refused rather than charged'), and that the identical call is resubmitted for the paid path, reinforcing the idempotentHint. The readOnlyHint and destructiveHint are not contradicted; the description actually strengthens them by describing a read-only, non-destructive return with no mutation of domain data.

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 well sectioned by topic (returns, data quality, quoting, charging, free alternative) and every section carries distinct meaning, but it is bloated with repeated all-caps emphasis (the paid/credential point is hammered across multiple sentences: 'ONLY priced tool', 'ONLY THING THAT NEEDS A CREDENTIAL', 'the handshake's no signup is about the free tier', 'Everything else here needs no account at all'). It is informative but not tight; roughly a third of the words re-drive the same paid-vs-free distinction.

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 and the presence of a nested authorize object plus a payment flow, the description fills the gaps: it enumerates the returned fields, explains the quote-to-authorization transition, states the data-population guarantee (19,881 confirmed loans, none estimated), and covers credential acquisition and the free fallback. Error handling and exact response shape are not specified, but the essential context for a correct call is fully provided.

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% for all four parameters and the nested authorize object, so the baseline is already high. The description adds marginal value on top, reinforcing that state drives pricing ('priced per state'), that limit does not affect price, and that authorize toggles quote vs. paid execution — but most of this is already stated in the schema descriptions, so the added semantic load is small.

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 the verb ('Returns'), the resource (LOANs, explicitly contrasted with events), the exact scope (one US state, one forward window, up to 200 loans), and the precise field list (maturity date, original principal, lender, instrument, origination date, property address). It also names the sibling tool it is not (search_property_events for events), so an agent can disambiguate without opening either schema.

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

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

Gives an explicit two-mode usage flow: omit authorize for a free quote, resend with authorize plus X-DFX-Account to be charged and served. It names the exact free alternative (search_property_events with event_type=LOAN_MATURITY_SCHEDULED) and gives the decision rule ('Use the free tool for timing, this one for a refinancing conversation'), plus the population difference driving that choice. It also clarifies who needs a credential (only this tool) and how to get one (open_dfx_account), so nothing is left to inference.

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

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

Annotations already cover read-only and idempotent, and description adds that it queries no data and is free, plus explains NOT_COVERED is measured not inferred. This goes 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 verbose with redundant phrases like 'stated plainly' and 'measured rather than inferred', and the structure repeats information about the two modes. It could be half the length without losing meaning.

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 explains the two output modes (full grid vs direct verdict) and the meaning of NOT_COVERED, providing sufficient context for correct usage. Could benefit from an explicit output structure, but overall it is complete.

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

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

Both parameters have clear schema descriptions ('Two letter state code', 'Same vocabulary as search_property_events'), and the tool description explains how they narrow the result. The enum is fully documented.

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 reports coverage ('Measured coverage, served sources, object types and the known gaps') and differentiates from search tools by clarifying it checks a coverage registry. However, the phrasing is ornate and could be more direct.

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 instructs to call before concluding absence ('Call this before concluding that an empty result means an absent market') and provides two calling modes: no args for full grid, with args for direct verdict. This gives unambiguous 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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description reinforces this with 'Reads' and 'Free'. It adds valuable behavioral context by explaining that payment advancement only occurs after DFX verifies a Stripe event and re-reads from api.stripe.com, giving the agent a clearer mental model of the underlying process.

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 and immediately gives actionable status semantics. Some phrasing is more rhetorical than strictly necessary, such as the examples of non-trustworthy payment signals, but those examples earn their place by preventing common misuse. Overall it is focused and not padded.

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

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

Since there is no output schema, the description compensates by explaining the two key statuses, AWAITING_PAYMENT and PAID, and their required follow-up actions. It also explains the trust model and the role of Stripe verification, which gives the agent enough context to use the tool correctly without needing additional documentation.

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 descriptions fully cover both parameters, and the description adds useful provenance for quote_id by tying it to the PAYMENT_REQUIRED reply and prior fund_dfx_account call. The account_key description also clarifies the conditional fallback when the X-DFX-Account header cannot be sent, which goes beyond a basic label.

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

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

The description clearly states the tool's purpose: reading the DFX payment ledger for a single quote. It also strongly differentiates this tool from related payment actions by calling it the 'ONLY trustworthy answer' to payment-status questions, which distinguishes it from sibling tools like fund_dfx_account and open_dfx_account.

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 guidance on when to use the tool and how to interpret its results: use it to confirm whether a payment went through, keep polling on AWAITING_PAYMENT, and proceed with the paid call when status is PAID. It also explicitly warns against relying on browser redirects, Stripe success pages, or client belief as substitutes.

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

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

Discloses the side effect of opening a payment, warns that the amount is read server-side and cannot be changed, and clarifies that card authorization and payment completion are separate steps. The annotations already indicate non-readOnly and non-idempotent behavior, and the description adds useful caveats without contradicting them.

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 somewhat lengthy with all-caps warnings, but each block conveys a distinct operational caveat. It remains focused and does not include irrelevant 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 there is no output schema, the description adequately names the return values (hosted payment URL and payment ID), explains the follow-up step (poll dfx_payment_status), and notes that this build only handles Stripe TEST payments. This is enough for an agent to use the tool correctly.

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

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

The schema already covers both parameters, and the description adds meaning by explaining quote_id's source and account_key's fallback purpose. This goes beyond simple type descriptions, though it does not need to elaborate further.

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?

Clearly states the tool opens a Stripe payment for exactly one quote, using the provided account key, and returns a hosted payment URL and payment ID. This distinguishes it from sibling tools like dfx_payment_status and open_dfx_account.

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

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

Provides explicit context for when to use it: quote_id comes from a PAYMENT_REQUIRED reply, and account_key is only needed if the MCP client cannot send the X-DFX-Account header. It also points to dfx_payment_status for polling, though it does not spell out every when-not scenario.

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, idempotent, and non-destructive behavior. The description adds a behavioral/data nuance: sales carry BOTH the instrument total and the parcel's allocated share because a deed repeats its full price on every parcel. This transparency about how output is computed goes beyond the annotations, though it does not mention side effects (which are already covered).

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 a single sentence followed by a clarifying sentence. It packs a lot of information (list of data components) without excessive verbosity. The structure is logical: first the main action and data items, then a specific nuance about sales consideration. No redundant words.

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 there is no output schema, the description serves as the sole explanation of the return data. It enumerates all major components: current state, dated events, relationships, debt details, sales records with registry info, and provenance. It also explains the sales allocation nuance. This is sufficient for an agent to know what to expect from the tool in a single-property 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?

The only parameter 'dfx_id' has a clear description: 'id returned by resolve_address'. This explicitly tells the agent where to obtain the value, covering 100% of schema parameters. Since there is only one parameter and no enums or nested objects, the semantics are fully specified.

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 purpose: given a DFX id from resolve_address, it returns a comprehensive record including current state, dated events, ownership/management relationships, debt details, recorded sales with consideration and registry book/page, and provenance. The title 'Everything DFX holds about one property or parcel' reinforces the singular comprehensive nature. It does not explicitly name sibling alternatives, 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 description provides a usage prerequisite: the DFX id must come from resolve_address. It also states 'Free.' at the end, indicating no cost. While it does not explicitly contrast with siblings like search_property_events, the title and 'Given a DFX id' imply this is the tool for a single property's full record. The clarification about sales allocation also guides interpretation of output, which is part of usage.

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 discloses important side effects: the key is returned once, only its digest is stored, it cannot be shown again, and the account starts at zero. It also clarifies that balance changes only occur through Stripe-confirmed payments, aligning with the readOnlyHint=false annotation.

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 somewhat repetitive with capitalized emphasis (e.g., 'NO money' and 'STARTS AT $0.00'), but each sentence adds meaningful operational detail. It could be tightened without losing crucial warnings.

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 core behavior, side effects, and usage conditions well despite the lack of an output schema. It does not specify exact output format or error scenarios, but it gives enough context for an agent to use the tool safely.

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?

All three parameters are described with added nuance beyond the schema. In particular, principal is clarified as a claim that is never verified and distinguished from the client software name, which prevents a common misuse.

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 creates an economic identity/account and explicitly notes it starts with no money. It distinguishes itself from sibling tools by emphasizing that free discovery tools do not need an account.

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: call only if intending to buy a paid capability, and states that all free tools work without an account. It also explains how quote_id affects the reply.

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, and non-destructive behavior. The description adds functional context by noting it is 'Free' and by explaining that the response includes typed objects ('property' and/or 'parcel') and states the match basis and ambiguity. This enriches the behavioral understanding 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 relatively brief yet packs essential information: the primary action, return types, overlap caveat, cost, and a forward pointer. No redundant sentences; each clause adds 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?

Lacking an output schema, the description adequately conveys the high-level response structure (canonical ids, typed objects, match basis) but does not detail the exact fields or shape of the result. Still, it provides enough context for an agent to understand what to expect and how to proceed.

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?

All four parameters have meaningful descriptions that go beyond basic type information. The city description clarifies precedence over parsed values, the limit description explains when to raise it (based on address_group_size), and the address description includes a concrete example. This exceeds the baseline for full schema coverage.

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: converting a street address into canonical DFX object ids, specifying the match basis and ambiguity handling. It differentiates from siblings by noting it returns both 'property' and 'parcel' types and by explicitly directing to 'get_property_record' next.

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

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

Provides usage context: 'Start here' signals the intended entry point for address-based queries, and the limit parameter description gives conditional guidance on when to increase it. However, it does not explicitly contrast with sibling tools like resolve_organization or search_parcels, which would make the 'when not to use' clearer.

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 provide readOnly, idempotent, and non-destructive hints. The description adds context about the blocking-key behavior and that it returns all candidates, which aligns with the annotations without contradiction. It doesn't mention side effects (none expected) but adequately supplements the annotation details.

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 concise and well-structured, using two sentences to convey the core purpose and key behavioral nuances. There is no redundant information or fluff.

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 mentions that the output is canonical DFX entity IDs and that candidates are returned, which implies a list structure. However, it does not explicitly state the exact return schema (e.g., array of objects) or error handling, leaving some ambiguity. Given the absence of an output schema, this is a minor gap but not critical.

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 descriptions for 'name' and 'limit' are thorough, explaining that 'name' accepts partial or differently punctuated company names and that 'limit' caps results at 50. The parameter semantics are fully covered and well-aligned with the tool's purpose.

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: resolving a company name to canonical DFX entity IDs. It also specifies the input type (owner, manager, lender, servicer name) and the nature of the output (candidates, not a single guess).

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 explains when to use the tool (when a name needs to be resolved to IDs) and when not to (person lookup is deliberately not offered). It also clarifies the behavior of returning multiple candidates rather than a single guess, guiding the agent's expectations.

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 annotations (readOnly, idempotent, non-destructive), the description adds key behavioral details: every answer includes the true match count alongside the sample, and a match-nothing search names the filter that emptied it. It also lists the output fields (assessed value, gross building area, etc.).

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 somewhat verbose and redundant, e.g., 'instead of one exact address' and later 'resolve_address needs an address you already have' convey the same idea. The trailing 'Free.' adds noise. It could be more concise while retaining the key points.

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 10 parameters and no output schema, the description covers essential context: it states that results carry specific fields, explains the sample/true-match-count behavior, and notes the empty-result behavior. Missing details like pagination or output structure are not critical given the absence of an output schema.

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

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

The schema already provides per-parameter descriptions at 100% coverage. The tool description summarizes the filter types (state, municipality, land use, owner-occupancy, tax-exempt, year built, assessed value) but does not significantly extend the schema details. However, it reinforces the purpose of each filter group, which is helpful.

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 searches the assessor parcel layer with filters, using the verb 'Search' and specifying the resource. It explicitly contrasts with resolve_address ('instead of one exact address'), making the primary use case unambiguous.

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

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

The description explicitly states when to use this tool (for filter-based queries) versus resolve_address (which needs an exact address), and notes that at least one filter is required. It also clarifies that the 'limit' parameter only sizes the sample, not the true result 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?

Beyond the read-only and idempotent hints, the description discloses concrete behavior: ordering by occurred_at ascending, default date flooring for expiry families, refusal of unreadable cursors and unrecognized event types, and that short pages do not indicate the end of results. It also explains the envelope's applied_date_floor and the effect of include_past, providing full transparency.

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 and dense, but almost every sentence carries essential caveats. It is well-structured with clear sections for families, filtering, paging, and forward-only behavior. However, some repetition exists (e.g., the statement that next_cursor null is the only signal of completion appears twice in slightly different forms), making it slightly less concise than ideal.

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 number of parameters (6) and the absence of an output schema, the description is remarkably complete. It explains paging, forward/backward temporal semantics, the distinction between expiry and historical families, and the envelope field applied_date_floor. It also addresses edge cases like empty results and cursor refusal, ensuring a caller has all needed context to use the tool correctly.

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

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

While the schema already describes each parameter, the description adds crucial semantic depth: within_days is strictly forward-only and cannot reach the past, include_past has no effect when within_days is given, and the event_type enum is generated from what the server actually publishes. It also clarifies the interplay between parameters and the meaning of cursor opacity.

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 provides dated events over US properties and parcels with provenance and a headline, and enumerates the event families covered. It distinguishes itself from siblings by its specific focus on event timelines and filtering, leaving no ambiguity about its role.

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 guidance on when and how to use the tool: it advises naming one event family to avoid mixing populations, explains forward-only windows and historical families, recommends calling dfx_coverage before interpreting empty results, and details paging behavior with cursor usage. It also clarifies when to omit within_days for backward-looking questions.

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 states 'records what was asked so unmet demand shapes what DFX builds next', implying a write/persistence side effect. This directly contradicts the readOnlyHint annotation, which indicates the tool does not modify state. Flagged as an annotation contradiction.

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 tight sentences with no filler. It front-loads the main action and outcome, then adds necessary behavioral notes. Highly concise and well structured.

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 there is no output schema, the description reasonably explains what the agent will receive (helpfulness answer, tool, arguments, sample, explicit no). Slight vagueness around 'free sample of the result' prevents a perfect score, but overall it is contextually sufficient.

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

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

The tool description itself does not add much parameter detail, but the input schema has 100% description coverage with rich explanations, including nested constraints behavior and enum vocabulary reference. Since schema coverage is high, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: given an objective, return whether DFX can help, which tool to call, arguments, and a sample. It also distinguishes itself by saying 'Call this first if you do not know what to ask for', positioning it as a routing/discovery tool 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?

Explicitly instructs when to use the tool: 'Call this first if you do not know what to ask for.' It also explains the behavior of saying no clearly and recording unmet demand, giving the agent clear expectations.

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