GISDB

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description still adds real context: cancellation is deferred to period end rather than immediate, and it discloses what comes back ('confirmed renewal and access status'). It does not say whether the cancellation can be undone before period end, which is the main remaining behavioral gap for a destructive operation.

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

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

Three short sentences with zero waste; the core action and its timing are front-loaded, and the pausing clarification is placed after the main statement where it belongs.

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 annotations covering the safety profile, an output schema covering return values, and a single fully-documented parameter, the description is nearly complete. The only missing piece an agent might need is recoverability/reactivation behavior for a destructive, deferred cancellation.

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

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

Schema description coverage is 100% and the single order_id parameter is thoroughly documented in the schema, so the baseline of 3 applies. The description only alludes to 'the selected subscription' and adds no format or sourcing detail beyond the schema.

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

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

States a specific verb + resource ('cancel the selected subscription's renewal') and pins down the timing semantics ('at the end of its paid period'), which is exactly the distinction an agent needs. It also rules out a nearby confusion ('pausing updates does not cancel renewal'), so it is separable from the account/billing 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?

Gives an explicit eligibility gate ('only when the user asks'), which is stronger than most mutation tools offer, and contrasts cancellation with pausing. It does not name a sibling alternative (e.g. open_billing_portal) for billing-management cases, so it stops short of full when-not 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 declare idempotentHint=true and destructiveHint=false, so the retry-key sentence largely restates structured data. The description adds the useful operational note that a changed source or offer must be re-reviewed, but for a non-read-only tool it does not explain what this call persists or how the workflow revision advances (that detail lives only in the schema).

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

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

Three short sentences with the action front-loaded and no filler. The middle sentence ("Review any changed source or offer") is slightly terse and could be ambiguous out of context, which keeps it from a 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?

With a full output schema and complete parameter documentation, the description doesn't need to explain return values. What remains thin is the resumption contract — what precisely is merged from prior answers/skips and how the revision advances — which an agent must infer from the schema alone.

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

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

Schema description coverage is 100%, so all four parameters — including the nested input object — are thoroughly documented in the schema. The description adds only marginal framing ("latest revision," "previous answers and skips") that maps onto fields already described. Baseline 3 is appropriate.

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

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

The description names a specific verb + resource ("Continue this saved search") and elaborates on state carried forward (latest revision, previous answers and skips). It distinguishes itself implicitly from gisdb_start_search and gisdb_get_search by framing this as resumption rather than creation or retrieval, though it never names the 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 retry rule ("Reuse a retry key only with identical arguments") and "Review any changed source or offer" imply when the tool applies, but there is no explicit 'use this instead of X when Y' routing against gisdb_start_search, gisdb_get_search, or gisdb_save_search, all of which are close siblings. Usage is implied rather than stated.

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=false, openWorld=true, idempotent=true, and destructive=false. The description adds important context beyond annotations: card details remain on the hosted page, the idempotency key should be reused after an uncertain response, and payment must be verified with gisdb_get_order.

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 four short sentences, front-loaded with the tool's purpose, followed by preconditions, security behavior, and retry/verification guidance. Every sentence contributes actionable information with no filler.

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

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

For a payment-link creation tool with open-world side effects, an output schema, and idempotent annotations, the description covers the necessary pre-call consent requirements, security handling, retry behavior, and post-call verification. Nothing essential for correct invocation 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 description coverage is 100%, so the schema already documents all four parameters thoroughly. The description reinforces idempotency_key reuse after uncertain responses, but adds no new syntax or meaning beyond the schema's parameter descriptions.

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: 'Create a secure payment link' for selected reviewed records, lead, or subscription offer. It also names the follow-up verification tool, gisdb_get_order, so the agent can distinguish this creation step from sibling billing and 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?

It gives clear preconditions: show price, coverage, update frequency, renewal and cancellation terms, and obtain the user's purchase request before calling. It also names gisdb_get_order as the verification tool. It does not explicitly list when not to use this tool, but the workflow conditions are strong.

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 only declare the safety profile (readOnly, idempotent, non-destructive). The description adds genuine data semantics beyond that: a failed check retains the last successful result, so absence of new records can only be concluded from a successful check, and subscription status is independent of delivery status. These are non-obvious staleness rules an agent could otherwise misreport.

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 short sentences, front-loaded with what is read; each clause carries semantic weight. The only minor waste is re-enumerating returned fields that the output schema already covers.

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 an output schema present and annotations covering safety, the description's job is behavioral nuance, which it delivers via the failed-check and status-separation rules. It is complete enough to call correctly; only the missing explicit sibling routing keeps it from a 5.

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?

Only one parameter at 100% schema coverage; the schema already explains workflow_id is an account-owned ID returned by saved-search tools. The description's 'this account's' reinforces ownership but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb ('Read') and resource ('this account's saved-search updates') and enumerates the data returned: delivery revision, source dates, check times, downloads. It does not explicitly name the counterpart gisdb_set_lead_updates or distinguish itself from gisdb_get_search, so differentiation is inferable rather than stated.

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

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

Usage is implied through interpretation rules (successful source check vs failed checks, subscription vs delivery status), but the description never says when to call this instead of siblings like gisdb_get_search, gisdb_list_saved_searches, or after gisdb_set_lead_updates.

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, non-destructive, and closed-world behavior, so the description adds real value beyond them: the explicit 'unavailable' outcome when no verified package exists, and the warning that CAD compatibility and the current tax year are not assumed, which tells the agent not to infer unverified facts. It stops short of describing response shape or field-level reliability.

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 tight sentences with the core purpose front-loaded and the failure mode immediately after. The closing sentence is dense jargon ('CAD compatibility') that isn't explained, which costs a little clarity but no words are wasted.

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?

No output schema exists, and the description does name the main return facets (verified details, source coverage, missing facts, limits) plus the empty-result case. It could say more about the response structure, but for a two-parameter read tool with full annotations it is nearly 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?

Schema description coverage is 100%, with both state (two-letter code, example TN/GA) and county (name or five-digit FIPS) already documented in the schema. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb ('Read') and a specific resource (a county records package's verified details), then enumerates what the payload contains: source coverage, missing facts, and limits. That resource is clearly distinct from sibling tools like gisdb_search_records or gisdb_get_search, which operate on searches rather than county packages.

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

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

Usage context is only implied by the note that it returns 'unavailable' when no verified package exists, which hints at a pre-flight confidence check. It never says when to call this versus gisdb_search_records or gisdb_get_search, and gives no prerequisites or exclusions.

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

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

The description goes far beyond the hints by revealing internal operational behavior. It explicitly states that the tool verifies 'payment, subscription, access and delivery separately,' giving the agent insight into the nature of the returned 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 highly dense but efficient, ensuring every phrase contributes to either usage context or behavioral disclosure. While slightly verbose, its clarity prevents unnecessary back-and-forth between agent and user.

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 that the annotations cover the safety profile and an output schema exists, the description provides all necessary context for the agent. It defines the scope, verification methods, and when the tool should be considered the source of truth.

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?

Since schema coverage is 100%, the baseline is high. The description adds valuable semantics by clarifying that the provided order_id must be 'Exact order_id returned by checkout or an earlier order response for this connected account,' which reinforces the required data source.

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: to verify the status of an existing account order. It distinguishes itself from general search tools by focusing specifically on post-checkout validation for a connected 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 provides extremely precise usage guidelines, instructing the agent to use the tool when facing an uncertain result or immediately after checkout. Crucially, it advises against trusting external sources like payment links, clearly defining the boundaries of the tool's utility.

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 behavior, so the description adds useful context: it rechecks sources and offers, preserves user preferences, and requires user confirmation for changed items. It does not describe authentication or response shape, but an output schema exists.

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

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

The description is two sentences with the primary action front-loaded and no obvious filler. The second sentence adds behavioral context, though 'Keep the user's preferences' is slightly vague.

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 full parameter schema, existing output schema, and read-only annotations, the description provides enough context for an agent to understand the tool's role and interaction requirement. It could be slightly more explicit about what 'sources and offers' means, but that is likely covered by the 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?

There is one parameter with 100% schema description coverage, including that it is the exact account-owned workflow_id. The description does not elaborate on the parameter beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description clearly states a specific action on a specific resource: reopening the account's saved search and rechecking its sources and offers. It distinguishes itself from sibling saved-search tools like list_saved_searches and save_search, though it does not explicitly name those alternatives.

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

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

Usage is implied by 'Reopen this account's saved search,' indicating it is for continuing work on an existing saved search. However, it gives no explicit when-not-to-use guidance or comparison with siblings such as continue_search or start_search.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely new behavioral facts: no sign-in or purchase is required, the call returns source coverage, previews and available offers, and unsupported notice categories never silently fall back to assessment records — an important data-integrity guarantee. The one-question-at-a-time turn discipline is also a behavior no annotation conveys.

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?

Five short sentences, front-loaded with what the tool finds before the interaction rules and output shape. Every sentence carries information. Docking one point because 'Unsupported notices never fall back to assessment records' is telegraphic and reads as a fragment without the surrounding schema context.

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 an output schema present, the description needn't explain return values, and it correctly summarizes them as coverage, previews and offers while covering auth ('no sign-in'), cost profile, and the iterative turn model. For a tool with a 10-field nested answers object and 14 siblings, the remaining gap is routing guidance versus gisdb_continue_search and gisdb_start_search.

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 baseline is 3; the description earns above that by explaining the accumulation contract ('resend previous answers and skipped IDs'), which tells the agent the answers object is stateful across turns rather than a fresh filter each call. It adds nothing about preview_limit/preview_offset beyond the schema, but the protocol-level semantics it contributes are the non-obvious part.

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 a specific verb (find) and enumerates concrete resources: property records, owner-name groups, lead packages, county downloads. The phrase 'Ask one next_question at a time' signals this is a conversational/guided search, which distinguishes it in spirit from direct-search siblings like gisdb_search_records. However, it never names those siblings explicitly, so the boundary with gisdb_start_search and gisdb_continue_search must be inferred.

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?

'Ask one next_question at a time' plus 'accept unknown or skipped answers and resend previous answers and skipped IDs' gives a clear interaction protocol for continuing a session. What is missing is when to pick this over gisdb_start_search, gisdb_continue_search, or gisdb_search_catalog — the presence of a continue_search sibling makes the routing ambiguity material. Usage is implied by the protocol, not stated against alternatives.

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

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

The annotations already declare this is read-only, idempotent, and non-destructive. The description adds useful context by noting that results include workflow IDs and revisions and by warning that a search's source should be checked before relying on 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 two sentences, front-loads the listing behavior, and follows with a relevant usage note. There is no wasted language.

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 input parameters, rich safety annotations, and an output schema, the description is complete enough for an agent to call the tool correctly. It even supplements the output schema by naming workflow IDs and revisions as relevant result fields.

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?

This tool has zero parameters, so there is no parameter meaning for the description to clarify. The baseline score of 4 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 gives a specific verb and resource: list the connected account's saved searches. It also distinguishes listing saved searches from reopening one to inspect its source, which helps separate it from siblings like gisdb_get_search.

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 clearly says the tool lists saved searches and advises reopening a search to check its source before treating it as current. The guidance is useful but does not explicitly name the alternative tool or state when not to use this one.

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=false, openWorld=true, idempotent=false, and destructive=false. The description adds meaningful context beyond those: payment details remain on a hosted page, and 'opening the page alone confirms nothing', clarifying that no local state change is guaranteed by the call itself. It does not cover authentication or failure behavior, keeping it from a 5.

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 compact sentences, front-loaded with the action. The second sentence handles privacy behavior, and the third handles confirmation semantics. Every sentence earns its place with no waste.

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?

An output schema exists, so return-value explanation is unnecessary. For a non-idempotent, open-world action, the description covers what happens, where payment data lives, and what must be done afterward. It stops short of covering error or authentication cases but is otherwise 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?

Schema description coverage is 100%, and the single order_id parameter is already fully documented in the schema. The description adds no further parameter-level meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Open secure billing for this account's order or subscription'. The purpose is immediately clear and consistent with the tool name. It does not explicitly name sibling alternatives like create_checkout or get_order, so it falls short of a 5.

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 'when the user asks' gives only implied usage, and there is no explicit comparison against create_checkout or get_order. However, it does provide a valuable follow-up rule: 'Read the order after returning to confirm any change', which guides post-invocation behavior.

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 non-readonly, non-destructive, idempotent, closed-world behavior. The description adds important domain semantics beyond annotations: saving has no purchasing or update-starting side effect, and a stale revision is rejected. This is valuable behavioral context, though it does not cover permissions or full error 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?

Three short sentences, front-loaded with the core action and its most important non-effect. Every sentence earns its place: purpose, billing clarification, and revision/retry instruction.

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?

Output schema exists, annotations are rich, and all parameters are documented in the schema. The description supplies the critical domain nuance that saving is not purchasing or activating updates, which an agent could not infer from structured fields. Minor gaps around permissions or failure modes are acceptable given the surrounding schema richness.

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

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

Schema coverage is 100%, so the schema already documents all four parameters thoroughly. The description reinforces the revision and retry-key semantics but adds no syntax or meaning beyond what the schema states, and does not discuss name or workflow_id. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Name and save this account's search') and immediately distinguishes the action from billing/activation siblings by clarifying that saving does not buy a subscription or start updates. An agent can tell this apart from start_search, create_checkout, and set_lead_updates without opening a schema.

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

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

Clearly implies the use case: retaining/naming an existing account search. It also gives concrete operational guidance ('Use the current revision and a stable retry key'). It does not explicitly name alternatives or exclusion conditions, but the billing/activation caveat provides strong contextual 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 establish that this is a read-only, idempotent, non-destructive, closed-world lookup. The description adds important domain behavior: it warns that a county listing does not confirm lead, assessment, or CAD coverage, and it directs the agent to verify package details before purchase.

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, front-loaded sentences with no wasted wording. It states the purpose first, then gives the verification guidance and the key coverage caveat.

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-parameter catalog search with full schema coverage and read-only annotations, the description is nearly complete. It gives the important caveat about county listings not confirming coverage, though it does not describe result shape or pagination behavior.

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

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

Schema description coverage is 100%, so the input schema already documents both parameters thoroughly, including that query is an optional county-name or FIPS filter. The description adds no parameter-level details beyond what the schema provides, so 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 uses a specific verb and resource: 'Find county records packages and directory listings.' This clearly distinguishes the catalog-browsing tool from sibling search tools, but it does not explicitly name an alternative or contrast with gisdb_search_records.

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 implies the tool is used before buying to check package availability, price, coverage, and limits, but it gives no explicit when-to-use/when-not-to-use guidance or alternatives. The buying context is helpful but not a full routing rule.

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, closed-world, non-destructive behavior, so the baseline is lower. The description adds meaningful context: JSON preview only, mode-specific row limits, no query/signal/offset support in owner_portfolios mode, and an important caveat that names do not prove identity, authority, debt, equity, distress, or intent to sell. It does not describe authentication or rate limits, but it adds substantial behavioral and interpretive context beyond 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 four compact sentences, front-loaded with purpose and mode selection, followed by limits and data interpretation caveats. Every sentence carries useful information, 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?

For a read-only search tool with no output schema, the description covers the essential context: two modes, when to use each, row limits, pagination restrictions, JSON-only output, and the critical caveat that owner names are not proof of identity or financial condition. Together with the detailed schema and annotations, an agent has enough information to select and invoke 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?

Schema description coverage is 100%, so parameter meanings are already richly documented in the schema. The description reinforces mode selection and row-limit differences between property_records and owner_portfolios, but it mostly restates constraints already present in the schema and does not add new syntax or format details. Baseline 3 is appropriate.

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

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

States a specific verb and resource: searching recorded county property facts or repeated owner-name groups. It clearly distinguishes the two internal modes, property_records and owner_portfolios, so an agent can tell what the tool does and how it differs from a generic catalog or metadata tool.

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

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

Explicitly routes between the two modes: use property_records for address, parcel or owner-name searches, and owner_portfolios for unfiltered groups. It also states row and offset constraints per mode. However, it does not explicitly distinguish this tool from sibling tools such as gisdb_search_catalog, gisdb_guide_search, or gisdb_start_search, so guidance is strong but not fully complete.

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 (idempotent, non-destructive, non-read-only) by disclosing that pause does not cancel renewal, that resume is gated on entitlement/source checks, and that a stale revision loses to a newer pause. Remaining gap: it doesn't say what happens to already-queued deliveries on pause or how a rejected resume surfaces to the caller.

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 short sentences, front-loaded with the action, then prerequisites, then side-effect caveat and conflict rule. Every sentence carries distinct information; nothing is restated from the schema or annotations.

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 mutating, idempotent tool with an output schema and full annotation coverage, the description supplies the preconditions, ordering with the read tool, and concurrency semantics an agent needs. Minor residual gap is the failure-mode surface (what an entitlement/source-check failure returns).

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 baseline is 3; the description adds cross-tool meaning the schema can't convey — expected_revision must come from gisdb_get_lead_updates and the idempotency key must be reused only with identical arguments. No extra detail on workflow_id, but that is already fully documented 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?

States a specific verb pair (pause/resume) and an exact resource (updates for this saved search/workflow), and pre-emptively separates itself from the sibling gisdb_cancel_subscription with 'Pausing does not cancel renewal.' An agent can route between this and cancel_subscription 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?

Explicit trigger ('when the user asks'), explicit ordering prerequisite ('Read updates first, then use its delivery revision'), and explicit preconditions for the resume path ('verified paid access and source checks'). The negative case (cannot override a newer pause) is also spelled out.

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 idempotentHint=true, destructiveHint=false and openWorldHint=false, so the retry advice and the "does not buy, subscribe or send anything" guarantee partly restate structured data. The description does usefully confirm no charge is incurred (worth saying given readOnlyHint=false), but it never says what is persisted or that the result is a workflow state with pending questions.

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

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

Three short sentences, front-loaded, with no padding. The first sentence is arguably inaccurate rather than wasteful, which is a correctness problem, not a length problem.

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?

An output schema exists, so return values need not be explained, and the input schema is exhaustive. What is missing is workflow context: that this is the entry point of a multi-step question/offer flow whose output feeds gisdb_continue_search, and how it differs from its two closest siblings.

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

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

Schema coverage is 100% and the nested answers object is heavily documented, including the idempotency_key retry rule, so the schema carries the semantics. The description's only parameter contribution (reuse the key on uncertain results) duplicates the schema text rather than adding to 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 states a verb and resource ("Save this GISDB search to the connected account"), but that phrasing collides with the sibling gisdb_save_search and does not explain what starting a search actually does (the schema implies it returns questions, products and offers). Without the schema, an agent cannot tell gisdb_start_search apart from gisdb_save_search or gisdb_continue_search.

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?

"Does not buy, subscribe or send anything" implicitly routes purchase intent to gisdb_create_checkout, and the retry instruction covers the uncertain-result case. However, the most important routing decision — use this to begin a new search vs. gisdb_continue_search for an in-progress one vs. gisdb_save_search — is never stated.

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