Untax

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

Annotations already establish read-only, idempotent, non-destructive, open-world behavior. The description adds useful boundary context by listing what the tool does not do (verify savings, quote fees, inspect payment methods, charge, create a filing packet, submit a correction) and by noting test checkout requires separate tools and account permission. It still does not describe the return format in detail, so this is not 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?

The purpose is front-loaded, followed by return behavior and negative scope, and no sentence merely restates the name. The test-checkout sentence is relevant boundary information and earns its place.

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 100% schema coverage and annotations covering the safety profile, the main remaining gap is output detail: no output schema exists and the description only says it returns "source facts and available actions." That is enough to select the tool but not fully describe the evidence payload.

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 are fully documented in the schema, including address precedence over parcel_id, county_key scope, and service_type aliases from get_microtransactions_catalog. The description adds no parameter-level meaning beyond those schema descriptions, 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 gives a specific action ("Research the selected property") and output ("show the evidence needed for the requested records service"), which clearly frames the tool as a read-only research step. It separates itself from payment and checkout actions, but it does not name the closest research sibling such as get_property_assessment, and the tool name audit_microtransaction is not echoed.

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 establishes when the tool applies ("requested records service") and gives explicit when-not conditions for fee verification, charging, filing packets, corrections, and test checkout. However, it only refers to "separate tools" instead of naming the specific sibling alternatives, so guidance is clear but not fully explicit.

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, the description explains that any submission is simulated, does not file a real appeal or change county records, and that a sandbox receipt is not county filing or external delivery. It also warns not to claim the draft is available until the order confirms its artifact is available, adding important mutation-state context not covered by readOnlyHint or destructiveHint.

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 main action is front-loaded and the operational guidance is organized around checkout, retry, and reporting states. It is longer than typical, but most sentences carry meaningful behavioral or safety information rather than repeating structured fields.

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 mutation's simulated nature, auth requirements, state-reporting expectations, retry behavior, and the distinction between sandbox completion and real filing or delivery. With no output schema, it still gives the agent enough context to invoke the tool correctly and interpret its results.

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 has 0% description coverage, but the tool takes only one simple parameter, order_id. The description clarifies that both get_tax_sandbox_order and complete_tax_sandbox_order take only order_id and explains when to reuse the known order_id, though it does not add format or validation 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?

The description states a specific verb and resource: checking a test payment for an order and making its draft PDF and receipt available once verified. It explicitly distinguishes this tool from get_tax_sandbox_order and start_tax_sandbox by describing which order_id-based actions each supports.

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 prerequisites (owner:sandbox sign-in and completed test checkout) and directs the agent to show the test checkout link when payment is pending. It also specifies when to read the same order after checkout or an uncertain failure, and when to retry start_tax_sandbox with the original idempotency_key instead of creating a new 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?

Adds context beyond annotations: the owner:va authorization requirement and the important side effect that 'Saved verification stays in Account until the owner removes it.' This clarifies what destruction actually means in this domain, though it doesn't explicitly say the connection can be re-established via start_va_connection.

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

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

Front-loads the action and scope, then layers prerequisites, side effects, and exclusions in short clauses. Every sentence earns its place without redundancy.

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 no parameters, no output schema, and annotations covering safety/idempotency, the description supplies what annotations cannot: required role and what is preserved after disconnect. A note on whether the disconnect is reversible would make it fully 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?

The tool has zero parameters, so there is no parameter semantics to explain. A baseline of 4 is appropriate; the description correctly avoids inventing parameter details.

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 (stop this assistant's access to this account's shared VA facts), which implicitly distinguishes it from get_va_connection and start_va_connection. The scope — this assistant, this account — prevents ambiguity with other connection operations.

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?

Includes a prerequisite ('Requires owner:va') and explicit exclusions ('Does not disconnect another account or assistant, submit a claim or change VA records'), which narrow usage. 'When requested' is slightly vague about who requests it, keeping it from a 5.

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

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

While annotations cover safety (readOnlyHint: true), the description provides critical behavioral constraints on the data itself. It informs the agent that the results are public information and that sandbox results are merely samples, which manages the agent's expectations regarding real-world accuracy versus simulated output.

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 definition is highly economical. Both sentences are focused, with the primary constraints and behavioral protocols strategically placed to guide the AI agent immediately after defining the tool's basic purpose.

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 high complexity of domain-specific, filtered search tools, the definition is extremely complete. It handles the core function, potential input deficiencies, output limitations (public/sandbox), and data classification constraints all within its text.

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

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

With 0% schema description coverage, the description provides significant semantic value by defining the domain boundaries (VA facilities vs. county offices) and explaining the filters. It clarifies that city and facility-type are 'optional filters,' guiding correct parameter construction, though it doesn't elaborate on specific parameter meanings.

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 ('Find') and resource ('official VA facilities'), and clearly defines the scope by listing optional filters (state, city, facility-type). It provides a strong operational definition of the tool's function.

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 explicit instructions on when to act and when to wait: 'If location is missing, ask the returned question.' Furthermore, it sets boundaries on usage by forbidding speculative behavior ('Do not guess a state') or misclassification ('present a VA facility as a county tax office or accredited VSO').

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 read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context about asking for a missing query, showing revision details and official PDF links, and not submitting claims.

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 short, front-loaded, and every sentence contributes: purpose, missing-query handling, return details, and scope boundary. There is 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 simple two-parameter search tool with rich annotations and no output schema, the description is largely complete: it covers purpose, fallback behavior, return details, and scope. It is slightly incomplete because it does not explain the limit parameter or when to use get_va_form instead.

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 explain both parameters. It clarifies that query accepts a form number or search text, but says nothing about the limit parameter or how result limiting works.

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: find official VA forms by number or search text. It is clear what the tool does, but it does not explicitly distinguish itself from the sibling get_va_form, which likely retrieves a single form.

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 says to ask which form or purpose is needed when the query is missing, and it rules out claim completion/submission. However, it gives no explicit guidance on when to use this search tool versus the singular get_va_form sibling.

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

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

Adds substantial context beyond the annotations: missing answers surface as review questions, extra answers are treated as user reports and not persisted, output is a protected expiring PDF, and the draft neither files an application nor decides eligibility. This is consistent with readOnlyHint=true since nothing is written back to the review.

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?

Purpose is front-loaded, followed by permissions, answer handling, and limits; almost every sentence carries distinct information. The caveat list at the end is dense but each clause (no official application, no eligibility decision, no savings estimate, no filing) sets a real expectation.

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 multi-permission, nested-parameter tool with no output schema, the description covers return format (expiring PDF), permission gating, and the crucial non-effects. The remaining gap is the un-narrated role of the two required ID parameters.

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 only 25%, and the description compensates partially by explaining how the nested 'answers' object is treated (missing vs extra answers) and the conditional semantics of use_connected_va_records. However, review_id and saved_property_id are never explained in the description, leaving some parameters documented only by bare types.

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 ('Create a free private veteran review PDF for the selected saved review'), clearly distinct from siblings like review_veteran_requirements or get_owner_review_details. The scope (per selected saved review) makes it selectable without opening the 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 clear preconditions: owner:read required, VA connection optional, and owner:va plus explicit per-applicant user choice needed for connected facts. It does not explicitly contrast with siblings like review_veteran_requirements, so the routing guidance is contextual rather than exhaustive.

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?

With readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false already provided, the description adds useful scope: it is a general checklist, not a property-specific lookup, and it explicitly disclaims verification of deadlines, fees, eligibility, and outcomes. It does not contradict 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 three short sentences and front-loads what the tool does before adding limitations. It is appropriately sized, though the opening sentence could be more specific about the appeal lifecycle.

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?

It explains what the tool is not and directs users to official rules, but it does not describe what the checklist actually covers, such as appeal stages or general review steps. With no output schema, that leaves a meaningful gap in understanding what the tool 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?

There are zero parameters, so the baseline is 4. The description has no parameter semantics to add, and none are needed for this zero-argument tool.

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 says it reads a general checklist for reviewing an assessment, but the tool name is get_appeal_lifecycle and the description never mentions appeals or lifecycle stages. It distinguishes itself from property lookup tools by saying it does not look up a property, yet the core resource is still vague relative to the name.

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 clear exclusions: it does not look up a property or verify deadlines, fees, eligibility, or outcomes, and it directs users to official rules. It does not explicitly name a sibling alternative, but the when-not guidance is strong enough to route an agent away from misuse.

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 readOnly, idempotent and non-destructive; the description adds real value by stating what each option exposes (status, evidence still needed) and drawing explicit outcome boundaries (no eligibility verification, no payable price, no savings, no refund approval, no filing authorization). This is exactly the behavioral context annotations cannot express, though return shape is not described.

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

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

Two sentences are front-loaded with the browse purpose, and the disclaimer is compact and purposeful rather than filler. The disclaimer list is somewhat long but each item earns its place by fencing off non-capabilities.

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 no-param, no-output-schema read-only browse tool, the description adequately covers both what the catalog shows and what it guarantees not to do. Nothing essential to calling it correctly is missing, though the absence of an output schema means a sentence on result structure would have completed 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?

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to clarify semantically.

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?

'Browse' gives a concrete verb and the resource is spelled out as property-tax research options plus the connection's available tools. It is clearly a discovery/catalog tool rather than an executor, though the name ('microtransactions_catalog') is slightly misaligned with the 'property-tax research options' phrasing and no sibling is explicitly contrasted.

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

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

The closing disclaimer implicitly tells the agent this is informational only and that actual verification/pricing/filing belongs to other tools, which is genuine routing guidance. However, it never names an alternative sibling (e.g., audit_microtransaction, start_tax_sandbox) or states a positive 'use this when' condition, leaving usage largely inferred.

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 safety (readOnly, idempotent, non-destructive, closed world), and the description adds genuine extra context: the owner:read permission requirement, the source of the identifiers, and the flags the caller must inspect. Disclosing that stale previous_owner_answers must be reconfirmed with the user is exactly the kind of behavioral caveat annotations cannot express.

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 action is front-loaded in the first sentence, but the body is a six-sentence prompt-like checklist mixing permissions, return-field inspection, and conversational policy ('Ask relevant unanswered questions and honor current answers and skips'). Each line is arguably useful, yet the density makes it harder to scan than a tighter two- or three-sentence version.

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

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

There is no output schema, so the description compensates by naming the key return signals a caller must branch on and by stating the auth and identifier prerequisites. What is missing is any statement of result shape or error behavior when the required permission is absent.

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% (only regex patterns, no descriptions), so the description must carry the load. It does say both IDs come from get_owner_workspace, which is useful provenance, but it never distinguishes review_id from saved_property_id or notes that both are mandatory and pattern-constrained.

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: 'Read the selected saved property review', and ties the resource to a prerequisite sibling (get_owner_workspace). It is a bit muddied by interleaved workflow instructions and by naming output fields (source_context_current, reconfirmation_required) that are never explained structurally, but the core action is 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?

Gives concrete preconditions ('Requires both IDs from get_owner_workspace and valid owner:read permission') and names an alternative for other cases: 'Use the protected browser review for changes and sensitive evidence', which implicitly excludes mutations from this tool. The alternative is not a listed sibling, so the routing is slightly less crisp than an explicit sibling reference.

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?

With annotations already declaring read-only, idempotent, non-destructive, closed-world behavior, the description adds useful context: the required revocable owner:read permission, that it returns property and review IDs, and that it does not verify ownership or filing authority. It stops short of pagination or empty-result 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 front-loaded with the core action and permission requirement, then adds return shape and guardrails in short sentences. Every sentence adds useful information without padding.

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

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

For a zero-parameter read tool with no output schema, the description covers the key points an agent needs: what is read, whose account, required permission, returned identifiers, ambiguity handling, and explicit non-guarantees. Nothing essential 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?

This tool has zero parameters, so the baseline is 4. The description adds no parameter detail because none exist, which 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 states a specific verb and resource: reading saved property reviews for the signed-in Untax account. It distinguishes the return shape (property and review IDs) from a details tool like get_owner_review_details, though it does not name that sibling explicitly.

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

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

It gives clear context: use it for the signed-in account's saved reviews, requires owner:read permission, and says to ask the user when ambiguous. It also warns not to assume an active property. It does not explicitly route between this and get_owner_review_details, which keeps it from a 5.

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

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

Beyond the read-only annotations, it discloses important limits: missing facts stay unknown, commercial building area is not living area, comparisons are drafts with evidence limits, and the tool does not verify savings or authorize filing. It also explains that skips only suppress prompts and owner answers do not verify eligibility or filing readiness.

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

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

The purpose is front-loaded, but the description is very long for a single read tool and mixes core behavior with detailed multi-turn workflow instructions. Several procedural points could be tightened or moved to agent-level guidance without losing essential tool-selection 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?

It covers the tool's domain, safety posture, and downstream workflow thoroughly despite having no output schema. However, it does not describe the return structure beyond 'records and their sources,' leaving some uncertainty about what a caller should expect back.

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 address, county_key, actual_sqft, address_or_pidn, and notice_appraised_value. The description adds some domain caveats relevant to square footage but does not provide parameter-specific syntax or selection guidance 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?

The first sentence states a specific verb and resource: read county assessment records and their sources for an address or parcel ID. It also names related tools like opportunity_screen and recheck_property_opportunities, making the tool's role distinguishable from those 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 routes the agent: review opportunity_screen for tax-reduction routes, ask targeted_questions one at a time, call recheck_property_opportunities after answers, and handle fact-only lookups by answering and offering screening. It also states how to treat skipped questions and when to summarize rather than continue.

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 annotations by defining critical states, such as reporting test payment and draft generation separately, and specifying exactly what constitutes 'availability' for a draft (artifact confirmation vs. just a URL). This is vital operational detail.

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 extremely verbose. While every sentence adds crucial operational context, the sheer length makes it poorly structured for quick consumption compared to a highly concise summary.

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 lack of an output schema and 0% input coverage, this description provides comprehensive completeness. It covers operational limits, legal disclaimers, idempotent usage rules, and required sign-in 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?

Since the input schema is minimal and coverage is 0%, the description is expected to compensate. However, it does not provide any additional semantic meaning for the `order_id` parameter itself beyond its use in a retrieval context, maintaining the baseline score.

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 purpose is highly specific: reading one's own 'Untax test order.' It clearly identifies the resource (test order) and the primary action (read), establishing a unique niche within the tax workflow.

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 detailed workflow guidance on how to use the tool in practice. It outlines when to retry the tool vs. when to use `start_tax_sandbox`, and clarifies the condition under which to use the tool (when an `order_id` is known).

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 readOnly/idempotent annotations: it discloses authorization requirements, that facts survive VA session expiry and server restarts, that revoked or expired app permission stops sharing, and that the data is a dated snapshot rather than a live check. It also bounds what the returned facts mean ('do not establish property ownership, primary residence, tax eligibility or filing authority'), which is exactly the extra context annotations cannot carry.

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

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

Front-loads the core purpose and access requirement, then layers persistence, staleness and scope disclaimers. Dense but every sentence carries information; the only mild redundancy is between 'active sharing permission' and 'expired or revoked app permission stops sharing', which restates the same gate from the opposite direction.

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 parameters and no output schema, the description carries the full burden and does so: it covers authorization, persistence across sessions, staleness and how to present results, plus explicit scope limits on the returned facts. An agent has everything needed to call it and to interpret the response responsibly.

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 takes zero parameters, so there is nothing for the schema to describe and no semantic gap to fill. Baseline 4 applies; the description's instruction to surface verified_at and freshness is a useful presentation hint rather than parameter documentation.

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: read the VA facts shared with this account. It also scopes what the resource is ('limited, dated VA facts') and negates a misconception ('saved snapshot, not a live check'). It does not explicitly name start_va_connection or disconnect_va_connection as the alternative paths, so sibling differentiation is left implicit.

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 clear preconditions for use: requires owner:va and an active sharing permission, and states that browser sign-in alone is not sufficient. It also frames when the data is stale ('reverification may be needed'). It stops short of routing the agent to the sibling tools that establish or tear down that sharing.

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?

Given that there is no output schema, the description is highly valuable for behavioral transparency. It explicitly lists the data returned (address, phone, website, source, environment) and clearly defines functional exclusions, providing context far beyond the generic 'Read' verb.

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 definition is highly efficient. The first sentence defines the core action and input, and the second sentence handles output and scoping. Both sentences are focused and contribute maximum 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?

The description is remarkably complete considering the lack of an output schema. It covers the input mechanism, specific return data fields, and ethical/functional limitations. Only the absence of an output schema prevents a perfect score here.

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 coverage is 0%, so the description must carry the full semantic burden. However, since the description merely states the tool is used 'using its returned id,' it doesn't add any unique functional meaning or data type nuance beyond what the input schema already provides.

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 one official VA facility. It distinguishes itself from sibling tools like 'find_va_facilities' by specifying that it uses a returned ID for a singular record lookup.

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?

While it does not explicitly reference sibling tools as alternatives, it provides critical usage boundaries by stating what it *does not* do, specifically that it 'Does not return private veteran records or decide eligibility.' This strongly guides the agent on when this tool is inappropriate.

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, so the description's added value is the disclosure of what is returned (title, revision details, official PDF link) and the important caveat that the link does not submit an application or establish eligibility — a meaningful guard against misuse in a benefits context.

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 the action and the example, then input sourcing, then return contents, then the caveat. Nothing is wasted, though the form_name guidance duplicates the schema text.

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 compensates by stating exactly what a call returns and what the result does not do. For a single-parameter lookup this covers everything an agent needs before calling.

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

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

Schema coverage is 100% and the schema's id field already states 'Official form number... Do not use the numeric catalog id', so the description largely repeats that guidance. The only marginal addition is the behavior when the value is absent, which is arguably usage guidance rather than 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?

States a specific verb and resource ("Look up a VA form number") with a concrete example (21-0966), which distinguishes it from the search-oriented sibling find_va_forms. It doesn't name the sibling explicitly, but referencing "search results" makes the relationship inferable.

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?

Implies it is a follow-up step to a search ("Use form_name from search results") and gives an explicit fallback when the input is missing: ask the user for the form number. Clear enough to act on without opening sibling schemas, though it never explicitly says when not to use it.

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, it discloses stateless recheck behavior, skip semantics, the need to resend still-applicable answers, and the fact that skips suppress prompts but leave requirements unresolved. It also clarifies that answers do not verify eligibility, evidence, savings, authority, payment, or filing readiness, which is rich behavioral context.

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

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

The purpose is front-loaded and most sentences carry operational guidance for a complex, stateful question flow. It is long and repeats the verification caveat near the beginning and end, so it is slightly redundant rather than maximally concise.

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 complex tool with no output schema, the description explains what is returned (research and next questions), how the question flow works, how rechecks are stateless, and what the answers do not establish. It gives an agent enough context to call and continue the interaction 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?

With 50% schema description coverage, the description adds important meaning for owner_answers and skipped_question_ids: preserve explicit false and empty arrays, omit unknown or skipped fields, resend stable skips, and do not transfer answers across properties. It does not explain every nested owner_answers field, so it compensates well but not completely.

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: reviewing possible property-tax options using county records and owner answers. It also distinguishes this screening/recheck flow from a fact-only lookup and from an audit or tax-reduction route, so an agent can identify its role without opening the 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?

It gives explicit when-to-use guidance: ask one targeted_questions item at a time, then call recheck_property_opportunities with accumulated owner_answers and skipped_question_ids. It also names alternatives and exclusions, including reviewing opportunity_screen for audits and avoiding an unrelated intake for fact-only lookups.

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

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

Adds substantial context beyond the annotations: an owner:va authorization requirement, disclosure that saved facts are 'not a live check' and carry a verified_at plus freshness indicator, and interaction rules (ask returned questions one at a time, accept unknown or skip, preserve explicit false). The annotations already cover read-only/idempotent safety, so this is complementary rather than duplicative; it does not describe rate limits or what the returned question objects contain.

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

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

Front-loaded with the core action and the optional-records condition before the operational rules and exclusions. It is dense with short imperative clauses; every clause carries a constraint, though the staccato fragments make it slightly harder to scan than a couple of well-formed sentences.

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

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

With no output schema, the description still tells the agent what comes back (questions to ask one at a time) and what provenance to surface (va_source.verified_at and freshness). Authorization, optional-input gating, and non-goals are all covered, so an agent has enough to invoke 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 67%, so the schema carries most field documentation, but the description adds real semantic rules the schema lacks: unknown answers are acceptable and skippable, explicit false must be preserved rather than treated as missing, answers stay bound to the same property, and connected VA records are used only when the user claims them. These constraints change how an agent should populate 'answers' and 'skipped_fields'.

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 ('Review requirements for the selected property') and scopes the inputs precisely: accumulated answers plus, only on request, the connected applicant's saved VA facts. It also draws a hard boundary against adjacent capabilities ('does not decide eligibility or savings, generate an application, or file anything'), which separates it from siblings like generate_veteran_packet and get_owner_review_details.

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

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

Gives a clear triggering condition for the optional path ('only when requested'), a prerequisite ('Requires owner:va'), and explicit exclusions of what it will not do. It stops short of naming a sibling tool to use instead for packet generation or eligibility, so routing is implied by the exclusions 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?

Adds substantial context beyond the annotations: no real charge or county filing, no verification of ownership/eligibility/savings/appeal window, test payments and separate test orders, and the requirement to report payment, draft generation, download availability and external delivery as distinct states. The safety and limited-side-effect profile is well disclosed; what it does not cover is what the response body actually contains beyond the checkout link.

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?

Purpose and the user-request gate are front-loaded, and most sentences carry operational weight. It is longer than typical, with a couple of advisory sentences (state reporting, not claiming draft availability) that stretch toward policy prose rather than tool selection 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?

For a high-stakes mutation with no output schema, it explains what is returned (a test checkout link, an order_id when available) and the follow-up read pattern. The notable remaining gap is the meaning of the service enum, which determines the kind of checkout being started.

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 had to carry all four parameters and it only explains idempotency_key (its retry semantics). address_or_pidn is only hinted at via 'the selected property', and county_key plus the appeal/microtx service enum are entirely unexplained, leaving the agent to guess the most consequential input.

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: 'Start a test checkout for the selected property', and clarifies it is a sandbox/test flow. It distinguishes itself implicitly from get_tax_sandbox_order and complete_tax_sandbox_order, which it names as separate steps, though it never says in one line what this tool is *not*.

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 explicit conditions: only when the user requests it, requires owner:sandbox sign-in, and directs the agent to read the same order after checkout or an uncertain failure rather than retrying. It also specifies the exact retry rule (reuse the original idempotency_key when no order_id was returned) and names which sibling tools take only order_id.

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 disclose that this is not read-only, is open-world, and is not idempotent. The description adds substantial behavioral context beyond annotations: the owner:va requirement, verification being saved only after approval, the fact that the link alone grants no access, and explicit secret-handling prohibitions.

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 purpose, then prerequisites, user flow, follow-up, and safety constraints. Every sentence adds useful operational or security guidance without padding.

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 still explains the key return/UI concept by instructing the agent to show connection_url and collect confirmation. It also covers authorization requirements, browser handoff behavior, persistence timing, and follow-up tooling, which is complete for a zero-parameter start tool.

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

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

The tool takes no parameters, so the baseline is 4. The description has no input parameters to clarify, and references to connection_url and fields to share describe expected outputs or UI behavior rather than inputs.

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

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

The description states a specific verb and resource: starting a requested VA connection for the signed-in account and assistant. It also distinguishes the follow-up step by explicitly naming get_va_connection after browser return, so an agent can tell the tools apart.

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 prerequisites and workflow: it requires owner:va, says to show connection_url, guides the user through saved verification or official VA sign-in, and instructs calling get_va_connection after browser return. It does not explicitly state when to avoid this tool versus disconnect_va_connection, but the operational context is 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?

The annotations already declare this as a safe, read-only, idempotent, non-destructive operation. The description adds important behavioral guidance by warning that similarity scores and is_auto_match are only hints and do not verify selection, owner authority, or financial eligibility, which is valuable context beyond the annotations.

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

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

The description is three tight sentences, front-loading the purpose and following with the ambiguous-case handling and an important caveat. Every sentence earns its place with no redundant or filler text.

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 low-complexity, read-only suggestion tool with full schema coverage and no output schema, the description is complete enough. It explains the matching behavior, ambiguity handling, and the meaning of key output hints like similarity scores and is_auto_match.

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 both the query and limit parameters are already documented with examples, constraints, and defaults. The description does not add parameter-specific semantics beyond the schema, so the baseline score 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 possible address matches in county records' from a partial query or misspelling. It clearly identifies the task and scope, and no sibling tool in the list appears to perform address suggestion, so the agent can distinguish it without opening the 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?

It gives clear usage context: use for partial queries or misspellings, and if the property is ambiguous, ask the user to choose before drawing conclusions or taking action. It does not name alternatives or explicit exclusions, but there are no obvious sibling alternatives for this specific suggestion task.

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