SwiftProbate

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

With annotations already declaring destructiveHint=true and non-idempotent, the description adds valuable context: it describes the outcome message (who it was assigned to or why it failed) and specifies that passing neither parameter unassigns. It stops short of detailing permissions or side effects (e.g., notifications), but the added behavioral clarity is strong.

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 well-structured sentences: purpose first, then parameter guidance, then unassign behavior. Every sentence carries necessary information 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 the tool's complexity (mutation, destructive hint, no output schema), the description covers key aspects: assignment targets, matching rules, failure outcomes, and unassign. It omits edge cases like reassignment behavior or notification side effects, but is sufficient for correct invocation.

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

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

Schema coverage is 100%, so all parameters are documented, but the description adds meaningful semantics: it explains matching rules for assignee_name (unique first name, 'People on this estate'), that assignee_user_id is an alternative, and that omitting both unassigns. This goes beyond the schema's basic 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 (assign) and resource (task), and clarifies the scope: to the estate owner or a collaborator who has accepted their invite. It also implicitly covers unassign behavior. An agent can distinguish this from create_task, edit_task, or update_task_status without ambiguity.

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

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

The description gives clear context for when to use assignee_name (as listed in 'People on this estate', first name works when unique) and explains that passing neither parameter unassigns. It also notes failure reasons (pending invite, no match, multiple matches). However, it does not explicitly name alternatives or exclusions among sibling tools.

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

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

Annotations already declare the safety profile (destructive, non-idempotent, open-world), and the description adds substantial context: it saves placeholder assets, triggers checklist generation that may research public sources and send a completion email, refuses an already-onboarded estate, and warns that partial failures are not safe to retry. This is behavior beyond what the annotations convey.

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

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

Front-loads the core action, then preconditions, side effects, and the retry caveat in dense, waste-free sentences. 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 destructive, multi-step onboarding mutation with no output schema, the description covers trigger conditions, side effects, refusal behavior, and the retry hazard. Nothing an agent needs to call it correctly 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% with all 7 params documented, so the schema carries parameter meaning. The description only advises collecting fields conversationally, adding little parameter-level detail. 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: 'Set up a new estate for the signed-in user and generate their personalized probate checklist.' It is clearly distinguished from siblings by contrasting with list_my_estates as the trigger, so an agent can tell when this onboarding flow applies versus a plain estate query.

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 names the condition: 'Use this when list_my_estates returns no estates (or one with no deceased details yet), or the user is just getting started.' It names the sibling that gates it and adds the operational instruction to collect fields conversationally before a single call.

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 by describing side effects the flags can't convey: adding an asset on an eligible paid estate may start public-source research and create asset-specific tasks, and recent same-name assets may get empty fields filled rather than duplicated. It also explains the dedup-window semantics behind idempotentHint=false, so the agent knows a later repeat can create a second asset.

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 purpose and the sibling disambiguation before the behavioral caveats, and most sentences earn their place. Minor redundancy: the dedup behavior is stated twice ("returns the existing one instead of a duplicate" and "Recent same-name assets may have empty fields filled instead of a duplicate being added"), which could be tightened.

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 13-parameter mutation with no output schema, the description covers the gaps that matter: side effects, dedup semantics, and the update-vs-create split. It stops short of saying what the call returns on success (e.g. the new asset id), which is the one thing an agent would still have to discover by 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%, so the baseline is 3. The description clarifies scope of asset kinds at a high level but adds no per-parameter meaning; the important guidance (customer_words, bypasses_probate, debts_liabilities, date_of_death_value) all lives in the schema descriptions. Adequate but not compensating 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 ("Create a new asset in the estate") and enumerates the concrete asset kinds it covers (bank account, property, vehicle, insurance, debt). It also explicitly distinguishes itself from update_asset, so an agent can route without opening the sibling 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 explicit when-to-use ("Use this when the user wants to add...") and names the alternative with its condition ("Use update_asset to change details of an existing asset"). It also resolves the exact ambiguity an agent would hit — creating a duplicate — stating that a same-name does not block creation.

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 a non-idempotent, non-destructive write, so the safety profile is covered. The description adds real behavioral context beyond that: a confirmation gate before saving, automatic normalization of non-canonical relationship wording, and integrity rules (never append a last name, never assume an adult). It omits what happens on duplicate heirs or what the call returns.

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 in the first sentence, then prerequisites, then the ambiguity trap. Three sentences, no filler, and the long final sentence is entirely the disambiguation rule that prevents the most likely data-entry error.

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 14-parameter mutation with no output schema, the description covers the decision gates that matter: who qualifies, confirmation of relationship, and how to record it. It leaves out duplicate handling and any note on the returned heir record, which an agent might reasonably want 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%, so the baseline is 3. The description still earns credit above baseline by adding policy the schema does not carry: the relationship must be confirmed against the deceased, ambiguous first-person phrasing must be re-asked with the given example, and any wording is accepted without re-prompting.

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 — 'Add a new heir to the estate' — and scopes it by enumerating who counts as an heir (spouse, child, stepchild, grandchild, parent, sibling, other relative). This clearly separates it from update_heir (modifying an existing record) and get_heirs (reading), so the agent can pick it without opening either schema.

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

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

Gives a clear trigger ('Use when the user wants to record a person who may inherit') plus a hard precondition ('Call once the customer has confirmed how the person is related to the DECEASED'). It does not name the sibling alternatives (update_heir, mark_heirs_complete) or state when not to use it, so it stops short of full when/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 readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the write/safety profile is covered. The description adds nothing behavioral beyond restating that it creates — no mention of whether estate_id must pre-exist, validation failures, or what is returned. With annotations doing all the work, the description contributes little.

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 short sentences with zero filler; the action is front-loaded and the usage condition follows immediately. Nothing redundant or padded.

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

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

For a create tool with full schema coverage and a complete annotation set, the description supplies purpose and a trigger. The main gap is that no output schema exists and the description doesn't say what comes back (e.g., the new task's id), which an agent may need for follow-up calls.

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 schema itself documents defaults, the priority scale, enum values, and ordering semantics for after_task_id/blocked_by_task_id. The description adds no parameter meaning at all, 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 and resource ("Create a new task in the estate"), which clearly separates it from read/update siblings like get_tasks, edit_task, and update_task_status. It doesn't explicitly name those siblings or state scope constraints, so it's clear but not maximally differentiating.

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 concrete trigger condition: "when the user identifies a new requirement or action item that should be tracked." That's real when-to-use guidance. It stops short of when-not-to-use or naming alternatives (e.g., edit_task for existing tasks, get_tasks to check for duplicates).

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 carry the behavioral weight (destructiveHint=true, idempotentHint=false, readOnlyHint=false), but the description adds nothing on top of them — no note that helpful_links is replaced wholesale, that deadline can be nulled, or that only supplied fields change (all of which live in the schema, not the description). With a destructive mutation flag set, a sentence on the destructive/partial-update nature would have been valuable.

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 short sentences, scoped field list front-loaded ahead of the usage cue. No filler, no repetition of the tool name.

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 partial-update mutation tool with no output schema, the description plus the unusually thorough parameter documentation cover what an agent needs: which fields are editable and that edits are field-scoped. The remaining gap is routing among the three update_*_task siblings, which the usage sentence does not resolve.

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 each parameter is richly documented (priority ordinal scale, ISO deadline format, markdown-link format for helpful_links, estate_id lookup instruction). The description only echoes the field list, adding no syntax or format detail beyond the schema, 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 (Edit) and resource (task) and enumerates the mutable fields: title, description, priority, deadline, category, helpful links. That makes the scope concrete and largely distinguishes it from read-only siblings. It stops short of explicitly differentiating from near-neighbors like update_task_deadline, update_task_status and update_task_notes, which overlap with fields listed here.

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?

"Use when the user wants to modify task details" is a restatement of the verb rather than real routing guidance. There is no when-not and no mention that update_task_deadline / update_task_status / update_task_notes are the narrower alternatives for single-field changes, even though those siblings directly overlap with this tool's deadline field.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered; the description adds the useful behavioral fact that this returns the *full* record (implied: more than the `search` summary) and lists the four record categories. It does not say what happens for an unknown or stale id, which is the main remaining gap.

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?

One sentence, front-loaded with the verb and resource, with the provenance constraint and the record-type enumeration packed into a single parenthetical. Nothing is wasted and nothing is buried.

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 one-parameter read-only fetch with full schema coverage and no output schema, the description supplies what the agent needs: where the id comes from and what class of record it returns. Only the not-found / invalid-id behavior is missing, which 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?

Schema description coverage is 100% and the single id parameter already carries an example and its provenance ('An id from a `search` result'). The description restates that provenance but adds no format, validation, or failure semantics beyond the schema, so baseline 3 is correct.

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 pairs a specific verb ('Fetch') with a specific resource ('full SwiftProbate reference record') and enumerates the record types it can return, so the agent knows exactly what comes back. It falls short of a 5 because it does not distinguish itself from apparent look-alike siblings such as get_state_overview, lookup_county_guide, or lookup_institution_guide, which the enumerated record types overlap with.

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 states the precondition clearly: the id must come from a `search` result. That is real usage guidance. However, it gives no exclusion against the several siblings that appear to retrieve the same kinds of content directly by name/state, so an agent cannot tell from this text when fetch is preferred over get_state_overview or lookup_county_guide.

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 the safety profile is covered. The description adds non-obvious domain behavior beyond that: some jurisdictions have no statewide fill-in forms, so omitting county can yield unusable results — a real caveat an agent needs. It omits pagination/result-count 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?

Two sentences, zero filler, and the what-it-returns inventory is front-loaded before the county guidance. The second sentence exists solely to prevent a foreseeable misuse (asking for statewide forms in a state that has none).

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 usefully enumerates the returned fields, and it covers the key required/optional parameter split. It doesn't mention result limits or ordering beyond the county-first nuance, so it is strong but not fully exhaustive.

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 three parameters including county's 'surfaces county forms first / omit for statewide' semantics. The description restates that plus the Florida example, adding only marginal meaning beyond the structured fields. Baseline 3 is correct.

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?

Opens with a specific verb+resource ('Find the probate forms for a jurisdiction') and enumerates exactly what each result contains (name, code, description, court source link, SwiftProbate page, county vs statewide flag). This is clearly distinguishable from siblings like lookup_county_guide or get_documents, which cover different resources.

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 conditional: pass the county when a state publishes no statewide fill-in forms (Florida cited), otherwise omit it for statewide results. It never names an alternative tool or states when NOT to use this one, so it stops short of 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?

Annotations already declare read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds meaningful context beyond annotations: the entry fields ('who', 'via'), the meaning of 'via' (SwiftProbate app, Grace, ChatGPT), and an anti-hallucination rule to state 'no record' rather than guess. It does not clarify what 'recent' means, how far back the log goes, or the ordering (newest first?), which are relevant behavioral gaps for a log tool.

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

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

Three tight sentences: purpose and scope first, output shape second, usage boundary and fallback third. Every sentence carries distinct information with no 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, two-parameter tool with no output schema, the description covers purpose, scope, return entry shape, and the critical fallback behavior when no record exists. Nothing an agent needs in order to call it correctly is missing, aside from the minor 'recent' window ambiguity.

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 both parameters, including the default limit of 20 and how to obtain the estate_id. The description adds no parameter-specific syntax or format details beyond what the schema 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?

States a specific verb and resource ('Get the estate's recent activity-log entries') and immediately defines scope ('who changed what, and when'). It explicitly distinguishes itself from sibling tools by saying it is 'not for task or asset contents, which have their own tools,' so an agent can route correctly 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?

Gives an explicit trigger ('when the user asks what has changed recently or who did something') and an explicit exclusion ('not for task or asset contents'). It also specifies the fallback when no matching entry exists, leaving almost nothing to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context by disclosing the return shape (asset details plus linked tasks), which matters because there is no output schema; it stops short of any auth or pagination notes.

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, zero filler, front-loaded with what is returned before the routing advice. Every clause carries information the agent needs.

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 correctly compensates by naming the return payload, and it explains where each required ID comes from (context block for asset_id, schema points to list_my_estates for estate_id). Complete enough for a two-param read 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?

Schema description coverage is 100%, so baseline is 3, but the description adds provenance guidance the schema lacks ('Get the asset_id from that context block'), helping the agent source the ID correctly rather than guessing.

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 ('Get one asset's full details plus the tasks linked to it, by asset ID'), and the scope word 'one' plus the linked-tasks payload cleanly separates it from the list-style get_assets and the task-scoped get_task_detail.

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 ('when the user asks about a specific asset's tasks or you need details beyond what the Assets context block shows'). No explicit when-not or named alternative, but the context-block threshold is a concrete 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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior context: assets are already surfaced in Estate Context, so this call is redundant except after mutations or truncation. It stops short of describing pagination or result ordering/size, which keeps 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 tight sentences, zero filler, and the core purpose is front-loaded before the usage caveat and the alternative-tool pointer. Every sentence carries decision-relevant information.

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

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

No output schema exists, but the description names the returned content (type and value), the sole parameter is fully documented in schema, and usage boundaries are explicit. An agent has everything needed to call this correctly and know when not to.

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?

Single parameter with 100% schema description coverage; the schema already documents estate_id and even points at list_my_estates for obtaining it. The description adds nothing about the parameter, 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 and resource ('List every asset in the estate') plus the returned fields ('with its type and value'), and explicitly distinguishes itself from the sibling get_asset_detail. An agent can tell which tool to pick without opening either schema.

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

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

Gives explicit when-to-use conditions ('only when you need the full set fresh... or the context block was truncated'), a concrete trigger example (right after creating/updating an asset), and names the alternative for the single-asset case. Both the positive and exclusionary guidance are present.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavioral context: the Documents context block already contains this list, making routine calls redundant. It stops short of describing pagination or return shape, but that is a modest gap given the annotation coverage.

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

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

Three sentences, no filler. The core action and filter scope are front-loaded, redundancy guidance follows, and the sibling pointer closes. Every sentence 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?

For a read-only list tool with no output schema, the description covers the action, the filter dimensions, the precondition (the data is likely already in context), and the route to the read tool. Nothing an agent needs to call this correctly 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% and each parameter is documented in the schema (including the instruction to call list_my_estates for the estate id). The description restates the filter semantics at a high level but adds no syntax or format detail beyond the schema, 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 ('List the estate's uploaded documents') plus the optional filter scope ('by asset or task'). It also explicitly contrasts itself with the sibling read_document, so an agent can separate listing from reading without opening either schema.

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

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

Gives an explicit when-to-call condition ('only to refresh after an upload or to filter to a specific asset's or task's documents') and names the alternative tool for the adjacent need ('To read a document's contents, use read_document instead'). This is exactly the when/when-not/alternative structure the top tier requires.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is covered. The description contributes the aggregation scope (it pulls assets, heirs, and task stats together) but says nothing about result size, freshness, or auth scope, so it adds only moderate value beyond the structured 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?

Two tight sentences with the content scope front-loaded and the usage condition second. Nothing is padded or repeated.

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 must carry return-value expectations — and it does by naming the four content categories the summary includes. It would be stronger if it hinted at the shape or relative cost of the aggregate call, but it is adequate for a single-required-param read 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?

With one parameter at 100% schema description coverage, the schema already explains estate_id and even instructs calling list_my_estates first. The description adds no additional parameter detail, 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 (Get) and resource (estate summary) and enumerates what the summary contains — details, assets, heirs, task statistics — which distinguishes it from the narrow getters like get_assets, get_heirs, and get_tasks. It stops short of naming those siblings explicitly, so an agent must infer the contrast.

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 activation trigger: 'Use this when the user asks about the estate overview or general status.' It does not, however, state when not to use it or route to the per-domain siblings (e.g., get_assets for a full asset list), leaving some selection ambiguity in a crowded sibling set.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioural context the annotations cannot: the data is normally present in a Heirs context block, this call is only a refresh mechanism, and that block can be truncated — which explains why the tool may return incomplete-looking or duplicate 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?

Two sentences, zero padding. The 'what it returns' clause leads and the usage constraint follows, so nothing has to be read twice.

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 single-parameter read-only list with no output schema, the description is nearly sufficient — it names the fields returned and the refresh-only purpose. It could say slightly more about return shape (ordering, pagination) if the list can grow large, but nothing blocking 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 coverage is 100% and the single estate_id parameter is fully documented in the schema, including the instruction to call list_my_estates first. The description adds no parameter-level meaning beyond that, 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 and resource ('List every recorded heir') and immediately scopes what is returned ('with relationship and details'). It also implicitly distinguishes itself from mutating siblings like create_heir/update_heir by framing this as the read path.

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 when-to-call rule: 'call this only to refresh after adding or updating an heir, or when that block was truncated.' It also names the alternative source of the same data (the Heirs context block), which is exactly the when-not guidance an agent needs.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing exactly what payload comes back (eight named facts plus prose and a URL), which effectively substitutes for the absent output schema. It stops short of stating freshness, caching, or coverage gaps for unusual jurisdictions.

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?

A single dense sentence that front-loads the purpose and follows with the returned fields; every clause names a distinct datum rather than padding. It is long, but the length is justified by enumerating eight return values for a tool with no output schema.

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 one-parameter read-only lookup with no output schema, the description is nearly self-sufficient: it tells the agent both the input scope (US state) and the complete return set. The only real gap is the absence of guidance on how this relates to the county/institution guide siblings, which would help an agent route 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% and the single 'state' parameter already documents all three accepted formats ('CA', 'California', 'california') in the schema itself. The description adds nothing beyond confirming the parameter is a US state, so the baseline 3 for fully-documented schemas 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 (Get) and a precise resource (high-level probate facts for a US state), then enumerates the exact facts returned: threshold, filing deadline, creditor-claim period, timeline, fees, UPC/community-property/independent-administration status, prose overview, and guide URL. This clearly separates it from siblings like lookup_county_guide, lookup_institution_guide, and get_estate_summary.

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 only implied: the word 'state' plus the enumerated state-level facts signal this is the state-scope lookup rather than a county or institution guide, but the description never says when to prefer it or names any alternative. No exclusions, prerequisites, or routing logic are given, so an agent must infer the boundary from the sibling list.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context by listing the returned fields (description, status, priority, deadline, notes, linked documents), which helps an agent know what data to expect.

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 a single, front-loaded sentence with no wasted words. It efficiently conveys the core purpose and the key return 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?

With no output schema, the description helpfully enumerates the returned fields. Annotations cover the safety profile, and the schema fully documents parameters. The only minor gap is the absence of error or edge-case behavior, but the definition is otherwise complete for a simple retrieval 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?

Schema description coverage is 100%, so both parameters (task_id and estate_id) are fully documented in the schema. The description does not add meaning beyond that, 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 ('Get') and resource ('full details of a specific task by ID'), clearly distinguishing it from the sibling list tool get_tasks. An agent can immediately tell this is a single-item retrieval operation.

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 states what the tool does but gives no explicit guidance on when to use it versus alternatives like get_tasks or edit_task. It implies the need for a task ID but does not name conditions or prerequisites.

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 safety, so the bar is lower. The description adds valuable behavior: default titles-only output, dashboard ordering, position and waiting_on semantics, up_next overriding other filters. Minor gap: doesn't mention pagination behavior for the limit parameter explicitly.

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?

Information is front-loaded with the core purpose first, then progressive detail. It's dense but each sentence conveys distinct behavior (default output, ordering, up_next, assignment fields). Slightly long, but nothing is truly 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, so the description carries the return-shape burden and does so well: titles by default, position, waiting_on, assigned_to/assigned_to_name. Combined with filters and up_next guidance, an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: include_description's purpose (jurisdiction/content review) and up_next's semantics (ignore other filters, match Overview page). These clarify intent beyond the schema text, justifying a 4.

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

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

States a specific verb+resource ('List tasks') and immediately scopes it with default return behavior (titles only) and ordering. The description clearly differentiates this list/overview tool from the sibling get_task_detail by emphasizing summary fields and filters.

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

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

Explicitly says what to filter by (status, category, asset, search term), when to add include_description (content-level review), and directly addresses the 'what's next' case via up_next: true. Multiple concrete use conditions are provided with no ambiguity.

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 safe, read-only, idempotent operation, but the description adds substantive behavioral context beyond them. It explains that `paid_by` is already resolved to the payer's name and must be used as-is, that `starting_balances` are not missing transactions, and what `totals` contains.

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

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

The description is front-loaded with the core purpose, then explains the returned data, then closes with a clear usage directive. It is dense but every sentence carries useful information, especially the caveats about `paid_by` and `starting_balances`.

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 supplies the return structure and meaning for `transactions`, `starting_balances`, and `totals`. It also covers the most important interpretive traps an agent could hit, making the definition complete for a read-only ledger 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?

Schema description coverage is 100%, and all three parameters are documented in the schema, including the `direction` enum values. The description does not add parameter-specific syntax or meaning beyond what the schema already 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 states a specific read operation — reading the estate's financial ledger — and breaks it into receipts, disbursements, and distributions. It names the returned `transactions`, `starting_balances`, and `totals` components, making it clearly distinguishable from write-oriented siblings like `log_transaction` and `update_transaction`.

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 an explicit usage directive: "Use this before answering any spending, reimbursement, or accounting question." It also warns that `starting_balances` are already in the ledger and should not be suggested for re-adding. It does not name alternative tools or when not to use this one, so it stops short of 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?

Annotations already cover readOnly, idempotent, and non-destructive, so the safety profile is set. The description adds valuable context the annotations don't: it describes the response shape (id, label, role, edit permission) and its role as an entry point for estate_id. It does not discuss pagination or empty-state behavior, so it falls short of 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?

Two tightly packed sentences: the first defines contents and return fields, the second gives the call-first directive. No filler, and the critical 'call this FIRST' instruction is placed where an agent will read it.

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, so the description carries the burden of describing what comes back — and it does, listing id, label, role, and edit permission. It omits edge cases like users with no estates and any pagination limits, but for a zero-parameter bootstrap tool this is close to 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?

Zero parameters, so the baseline is 4. The description appropriately spends no words on nonexistent inputs, and instead documents the output fields an agent will need to extract.

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 (list) and resource (estates) with precise scope: the signed-in user's estates, owned or shared. It also enumerates the returned fields (id, label, role, edit permission), which cleanly distinguishes it from siblings like get_estate_summary or get_assets.

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 tells the agent when to call it — FIRST — and why: every other estate tool needs an estate_id from here. This is a textbook sequencing guideline that routes the agent through the tool graph.

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 annotations: it explicitly says the tool records a bookkeeping entry only and does not move money, and that duplicate detection is time-limited so a repeat call may create a second entry — directly explaining the non-idempotent behavior declared in annotations rather than contradicting it.

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

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

Front-loaded with the core purpose, then examples, then the confirmation prerequisite, then the edge-case notes (bookkeeping-only, duplicate behavior). Every sentence carries actionable information and none are redundant with the schema.

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 12-parameter mutation with no output schema, it covers the critical gaps: mutation semantics, duplicate risk, required confirmation, and payer attribution. It does not say what is returned on success (e.g. a transaction id), which would help an agent chain into update_transaction, so it falls just short of 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic guidance: administration expenses map to direction='disbursement', and paid_by='individual' vs empty payer_name vs named payer_name encodes the reimbursement logic that the schema only partially conveys.

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 ('record a financial transaction in the estate ledger') and enumerates the scenarios that qualify (expense, income, debt payment, distribution), which cleanly separates it from read-only siblings like get_transactions and from update_transaction.

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 trigger ('when the user mentions money moving') plus realistic example utterances and a mandatory pre-check ('ALWAYS confirm the amount, what it was for, and who paid'). It does not explicitly name alternatives such as update_transaction for correcting an existing entry, so it stops short of 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?

Annotations already establish readOnly, idempotent, non-destructive, and closed-world behavior, so the bar is lower. With no output schema, the description usefully discloses what the caller receives (verified address/phone/website, fee, approved newspapers, e-filing system, forms), which is genuine added value; it does not cover miss/not-found behavior or caching.

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, zero waste: the first front-loads what is returned, the second front-loads when to use it and why. Nothing is repeated 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 two-parameter, read-only lookup with no output schema, the description is nearly complete: it tells the agent the domain, the trigger condition, and the shape of the returned data. It lacks only edge-case behavior (county not found, unmatched county names) to be fully self-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 both parameters (state, county) are documented in the schema itself, including accepted formats for state. The description only implies the county/state scoping and adds no format or matching nuance beyond the schema, 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 ('look up') and resource ('SwiftProbate's published probate guide for a specific US county') and then enumerates exactly what the guide contains: courthouse contact info, filing fee, approved newspapers, e-filing system, and county forms. An agent can distinguish this from lookup_institution_guide purely from the county-court framing and returned field list.

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 triggering context — 'use this before answering any question about a county court's contact info, filing fees, or publication requirements' — plus a rationale (county details are unreliable from model knowledge). It stops short of naming a sibling alternative or stating when-not to use it (e.g., vs. lookup_institution_guide), so it does not reach the explicit-routing bar of 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?

Annotations already declare this a read-only, idempotent, non-destructive, closed-world lookup, so the safety burden is covered. The description adds real value by disclosing the shape of the returned record (department phone/hours/fax, mailing and overnight addresses, online notification URL, document checklist, probate-required account types), though it says nothing about coverage limits or what happens when an institution is not found.

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?

Single dense sentence with the verb and resource front-loaded, and the enumerated return fields follow in a scannable list. It is efficient, though the long parenthetical audience list and field roll-call make it heavier than strictly necessary.

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 must convey the return contents, and it does so explicitly by enumerating the guide's fields. Combined with the clear single-parameter call contract, an agent has everything needed to invoke and interpret the result.

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 both parameters ('institution' and the optional 'category' hint) carry their own descriptions with examples, so the schema does the heavy lifting. The description adds no extra semantics about matching behavior (e.g., fuzzy name matching or what happens on ambiguity), 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?

Specific verb ('look up') plus a precisely scoped resource (SwiftProbate's estate-notification guide for financial institutions), with the target audience enumerated (banks, brokerages, life insurers, credit unions). It also lists the exact fields returned, so an agent can instantly distinguish it from siblings like lookup_county_guide or find_probate_forms without opening any 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?

The audience and subject imply when it applies (you need contact/notification details for a bank, brokerage, or insurer), but the description never states when to prefer this over lookup_county_guide or find_probate_forms, nor any prerequisite like needing the estate's jurisdiction. Usage is inferable but not 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 declare the mutation/safety profile, and the description adds substantial side-effect detail beyond them: it changes the asset-collection flag and derived estate facts, and for eligible paid estates may start public-source research, add checklist tasks, and send a completion email. This is exactly the escalation behavior an agent needs to know before triggering 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?

Front-loaded with the core action and the trigger conditions, and every sentence carries operational information. It is somewhat long and restates the 'list is complete' point several times, which costs a little tightness on a single-purpose tool.

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

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

For a one-parameter, no-output-schema tool, the description covers purpose, triggers, prerequisites, timing, and downstream side effects, which is everything an agent needs 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?

Only one parameter, and the schema already documents estate_id at 100% coverage including the 'call list_my_estates first' guidance. The description adds no parameter-specific 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 action on a specific resource: recording that the user finished describing the estate's assets. It explicitly distinguishes itself from create_asset ('this tool records that the LIST is finished, it does not save assets'), so an agent can tell it apart from its closest sibling without opening either schema.

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

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

Gives explicit trigger phrases ('that's everything', 'the only asset'), the prerequisite (every asset already saved via create_asset), timing (same turn, do not ask for a second confirmation), and a constraint on repeat calls (only once the list is final). Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true and non-idempotent; the description adds real context beyond them — it changes the heir-collection flag and derived estate facts, and explicitly does not start paid checklist generation. It doesn't address reversibility or why the operation is flagged destructive, which is the remaining gap.

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, then prerequisites, then the exception — a logical progression. It is on the long side and repeats the 'facts stay unknown' consequence twice, but nearly every sentence carries operational 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?

Two simple parameters, no output schema, full schema coverage; the description supplies timing, prerequisites, exception handling, and side-effect boundaries. Nothing an agent needs to invoke this correctly 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 coverage is 100%, so the baseline is 3, but the description goes further by stating the exact condition under which confirmed_no_heirs should be set — after explicit user confirmation that no heirs exist — which the schema states more compactly. estate_id meaning is left to 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 and resource — recording that the user finished naming heirs — and implicitly distinguishes itself from create_heir (which saves individuals) and mark_assets_complete. An agent knows exactly what state transition this performs.

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 triggers ('the moment they say that's everyone', with example phrasings), a prerequisite (every named person saved via create_heir, including a spouse), a same-turn instruction, and an exception path for zero heirs. Very strong, though it does not name a sibling as the alternative for the zero-heir case.

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 the safety profile (read-only, idempotent, non-destructive) and the closed-domain hint. The description adds real context beyond that: results are a list carrying ids, and the intended next step is `fetch` for the full record, which is a meaningful chaining behavior. It omits result limits, ranking, and empty-result behavior, keeping it out of the top band.

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 resource scope, then the return shape, then the usage rule. No sentence is filler and nothing is buried.

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 correctly takes on the job of explaining what comes back and how to continue via `fetch`. It is slightly thin on result volume and how to refine a query that returns nothing useful, but it covers everything an agent needs to make a correct first call.

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 single `query` parameter is fully documented in the schema, including two illustrative examples, so the schema carries the load. The description only characterizes the query as 'open-ended', adding no syntax, phrasing, or scoping guidance beyond what the 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?

States a specific verb (search) and a clearly bounded resource: probate reference data over US states, counties, financial institutions, and court forms. It does not explicitly distinguish itself from siblings like lookup_county_guide, lookup_institution_guide, or find_probate_forms, which are clearly narrower lookups an agent would need to choose between.

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?

'Use it for open-ended probate reference questions before answering from model knowledge' gives a clear selection context, and the word 'open-ended' implicitly contrasts with the targeted lookup siblings. It stops short of naming those siblings or stating an exclusion rule, so the agent must infer when to prefer a dedicated lookup.

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 destructiveHint=true and non-idempotent, and the description adds real context beyond that: type changes preserve linked tasks, documents and ledger entries, while delete-and-recreate 'would wipe its tasks'. It still doesn't say the update is a full/partial replacement or that clearing a field is irreversible beyond the schema's own note.

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

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

Three sentences, front-loaded with purpose then the sibling distinction then the clear_fields escape hatch. No restatement of the name and 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 16-parameter mutation with no output schema, the description covers the decisions that matter (update vs. recreate, type correction, clearing). It doesn't describe the return value or the customer_words gating for probate/beneficiary flags, leaving those to the 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?

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the clear_fields mechanism ('to empty a field, list it in clear_fields') and the consequence of asset_type, which are the two parameters most likely to be misused. It adds nothing for the remaining 14 params, which the schema already handles well.

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?

Specific verb plus resource plus the fields it touches (name, type, value, jurisdiction, notes), and it explicitly separates itself from create_asset ('use this instead of creating a duplicate'). An agent can tell it apart from the siblings 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?

States when to use it (modifying an existing asset), when not to (creating a duplicate, deleting and recreating), and names the corrective path for a wrong type — change asset_type here. It also routes field-emptying to clear_fields, which is otherwise a counterintuitive operation.

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 real context beyond the annotations (destructiveHint=true, idempotentHint=false): 'Always confirm changes before calling', the jurisdiction-change sequence, and the disclosure that resolving will status removes the will-determination task and adds succession tasks. The one gap is partial-update semantics — 'Replaces supplied estate details' does not clearly say that fields omitted from the call are left untouched, which matters for a destructive non-idempotent write with 28 params.

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 definition, then ordered by descending risk (exclusions, operating account, EIN, confirmation, jurisdiction flow). It is long, and the repeated 'It is ALSO where...' construction plus all-caps emphasis adds some noise, but nearly every sentence carries a routing or safety 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?

For a 28-parameter destructive write with no output schema, the description covers confirmation, side effects on tasks, and the ambiguous-field routing. It does not state what the tool returns or whether omitted fields are cleared, which is the remaining surface an agent needs for a safe non-idempotent update.

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

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

Schema coverage is already 100%, so the baseline is 3; the description goes further by disambiguating the two highest-risk pairs (ein vs estate_number, estate_account_* vs create_asset) and by flagging the estate_number/estate asset boundary in prose the agent will read before the schema. It does not add much for the address and executor fields, but those are already fully self-describing.

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 ('Update high-level estate details') plus the trigger condition ('that the user can correct after onboarding'). It then explicitly carves out what belongs elsewhere (create_heir, create_asset, mark_heirs_complete/mark_assets_complete), so an agent can separate it from all four siblings 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?

Gives positive triggers with concrete utterances ('actually there is a will', 'the case number is 2026-001234'), explicit exclusions ('NOT for who the heirs are or what the estate owns'), and named alternatives for each excluded case. It even routes two easily-misfiled facts (the operating account and the EIN) away from create_asset and estate_number with stated reasons.

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 destructiveHint=true, readOnlyHint=false, and non-idempotent, so the safety profile is covered upstream. The description adds only an implicit cue that this is a partial 'correct or add' edit rather than a full replacement; it never says whether omitted fields are preserved or how relationship_confirmed gating behaves. For a destructive 15-parameter mutation, that is a modest addition over 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?

Three short sentences with the purpose first, the triggering condition second, and the ID prerequisite last. No filler or restatement of the schema.

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 15 parameters, destructiveHint=true, and no output schema, an agent still has an open question the description could answer: are unspecified fields left untouched or cleared? The rich schema partly compensates for name/relationship semantics, but partial-update behavior and confirmation gating are only inferable.

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 per-parameter text is unusually rich (empty-string clears, canonical relationship values, relationship_confirmed requirement), so the schema carries the semantic load. The description only contributes the sourcing hint for heir_id from the pre-loaded Heirs context block.

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 ('Update an existing heir's details'), which cleanly separates it from create_heir and get_heirs. It doesn't name any sibling explicitly, so it falls short of full differentiation, but the mutation target is unambiguous.

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

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

'Use when the user wants to correct or add information to a recorded heir' gives a clear triggering condition, and the second sentence supplies the prerequisite for heir_id. No alternatives or exclusions are named (e.g. use create_heir when the person isn't recorded yet), so it stops short of 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?

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: no note on what clearing destroys, no permission requirements, and no statement about reversibility.

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 short sentences, front-loaded with the action and followed by the trigger condition. Nothing redundant or padded.

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

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

For a three-parameter mutation with full schema coverage and annotations, the description is minimally sufficient, but it leaves the destructive clearing case and any prerequisites unaddressed. Adequate with clear gaps.

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

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

Schema description coverage is 100%, so all three parameters (including the null-to-clear semantics of deadline) are documented in the schema. The description's phrasing 'set or clear' only echoes this, adding no new parameter detail. 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 and resource: 'Set or clear a task's deadline.' An agent can distinguish this from update_task_status and update_task_notes by the 'deadline' resource. It does not explicitly name those siblings, 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?

Gives one usage cue ('when the user wants to set a due date') but omits the clearing scenario, which the tool also supports, and names no alternatives or prerequisites. Usage is implied rather than fully scoped.

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 destructiveHint=true and idempotentHint=false, so the safety profile is partly covered. However, the description never states the key behavioral fact for this tool: existing notes are overwritten (the schema alone hints at this via 'empty string to clear'), nor does it mention permissions or whether history is retained. 'Set or update' undersells a destructive replace.

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 short sentences with the action front-loaded and no filler. The second sentence is largely redundant with the first, which keeps it just short of 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?

For a destructive mutation with no output schema, the description is adequate but thin: it omits that notes replace existing content, and says nothing about prerequisites beyond what the schema states. Annotations cover the safety flag, so the gap is not severe, but the overwrite behavior is the one thing an agent most needs.

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 all three parameters carry descriptions, including the useful 'empty string to clear' semantics for notes and the pointer to list_my_estates for estate_id. The description adds nothing beyond the schema, 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?

The description names a specific verb pair and resource: 'Set or update the user notes on a task.' That is clear enough to distinguish from status/deadline siblings, but it never explicitly contrasts with edit_task, which an agent might reasonably assume also touches notes. Clear purpose, no sibling differentiation.

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?

'Use this when the user wants to add notes to a task' is a restatement of the purpose rather than guidance — it gives no alternatives, no when-not condition, and no hint about how it relates to edit_task or update_task_status. An agent gets no routing information beyond what the name already implies.

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 by disclosing the consent policy: completing or marking not required is the customer's decision, requires quoted customer_words, and the agent must ask rather than infer. It does not mention reversibility or consequences of a mistaken update, which matters given destructiveHint=true.

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 front-loaded sentences with no filler; the core action comes first, followed by the consent rule and the recovery case. Slightly dense but every sentence 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?

Covers the non-obvious hazards (acting without consent, restoring a not-required task) for a 4-parameter mutation tool with no output schema. Missing only the standard mutation caveats such as reversibility and audit side effects implied by destructiveHint=true.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning by framing customer_words as a policy gate rather than a free-text field and by explaining the not_applicable -> not_started transition. It still doesn't clarify estate_id lookup or the semantics of the other two enum values.

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 ("Update a task's status") that is immediately distinguishable from edit_task, update_task_deadline and update_task_notes. It does not explicitly name those siblings, so it stops short of 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?

Gives concrete triggering conditions ("when the user asks to mark a task as completed, in progress, etc.") plus a restore path for not_applicable -> not_started. It never names the alternative sibling tools, so routing among update_variants is left implicit.

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 destructiveHint=true, readOnlyHint=false, idempotentHint=false, so the bar is lower. The description adds the partial-update behavior (omitted fields preserved) and a required user-confirmation workflow, though it does not spell out what a direction/category change destroys or how failures surface.

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

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

Four sentences, front-loaded with the purpose, then prerequisite, then the partial-update rule, then the confirmation requirement. No filler; each sentence carries a distinct 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?

For a 12-param destructive mutation with annotations but no output schema, the description covers purpose, prerequisite lookup, partial-update semantics, and a safety confirmation step. It stops short of describing error/rollback behavior or the direction-change cascade, leaving minor gaps.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds a rule the schema does not encode: this is a PARTIAL update where omitted fields are left as-is, and transaction_id must accompany only the changed fields. That meaningfully changes how an agent fills the 12-property payload beyond the per-field schema text.

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 (correct/update) and resource (ledger transaction) and enumerates the correctable fields (amount, date, category, payee, who paid, heir/asset). It explicitly distinguishes itself from creating a new correcting entry, so an agent can separate it from log_transaction without inspecting schemas.

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 prerequisite ('Find the transaction's ID with get_transactions first'), names the alternative it is not ('Use this (not a new correcting entry)'), and adds a confirmation step before calling. When-to-use is tied to the user-facing trigger ('the user says an amount or detail was wrong').

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