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

Annotations already disclose that this is a non-readonly, non-destructive, non-idempotent, closed-world mutation. The description adds a useful privacy/safety instruction about not using full account numbers, but does not explain side effects, permissions, or what happens to duplicate submissions despite the non-idempotent hint.

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

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

The description is two short sentences with the purpose stated first and the parameter guidance second. It is efficient, though the second sentence mixes two separate constraints in a way that could be clearer.

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

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

An output schema exists, so return values need not be explained. However, for a six-parameter creation tool with 0% schema description coverage, the description is too thin: it does not document most parameters, defaults such as status='draft,' or behavioral expectations around the create operation.

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

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

Schema description coverage is 0%, so the description must compensate. It only addresses party_type values and item_description content; party_name, reason, status, and sent_date are left undocumented, and party_type enum values are already present in the schema.

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

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

The description says 'Start tracking a dispute,' which conveys creation of a dispute record. It is reasonably clear as a distinct action from list/get/update/delete siblings, though 'start tracking' is softer and less precise than 'create.'

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 a narrow data-entry guideline ('use the item's description, not full account numbers') but does not explain when to use this tool versus disputes_update, disputes_get, or other siblings. No exclusions or alternative routing are provided.

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 readOnlyHint/openWorldHint annotations: it explains the deadline is counted from the recorded sent date so the real date is the same or later, and it explicitly discloses what the tool cannot know (clock start, 15-day extension, furnisher extension), plus a 'not legal advice' caveat. That is exactly the kind of computed-estimate limitation an agent needs before presenting results.

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 and output contract, and the operational notes (as_of, paging) sit at the end where they belong. The two full statutory citations with URLs are long but arguably earn their place by grounding the 30-day rule; they could be compressed.

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

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

An output schema exists, so the description need not explain return values, yet it still names the key fields and the limitations of the computation. The main residual gap is the undocumented limit parameter and the absence of explicit sibling routing.

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

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

Schema description coverage is 0% across three parameters. The description compensates for as_of (YYYY-MM-DD format, purpose of checking another day) and offset (paging via next_offset) but never explains limit or its default of 20, so the coverage gap is only partially closed.

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+resource (returns open disputes in draft/sent/response_received states with their statutory response deadline) and enumerates the outputs: days remaining, overdue flag, next action. It is clearly distinct from a plain list tool, though it never names disputes_list as the alternative, so sibling differentiation is inferred rather than stated.

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

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

Usage is implied by the content: check deadlines, pass as_of to evaluate another day, page with offset=<next_offset>. There is no explicit statement of when to use this versus disputes_list or disputes_get, and no when-not guidance, so the agent must infer the 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 say destructive/non-readonly, and the description adds substantially more: the preview-vs-execute split, the approval gate and pre-approval settings override, and the side effect that letter files on disk survive deletion. The assistant's inability to self-approve is a critical, non-obvious behavioral fact that annotations cannot express.

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

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

Five short sentences, front-loaded with the action, then the confirm semantics, then the side effects and the approval constraint. No filler and nothing repeated from annotations or 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?

An output schema exists, so return-value explanation is unnecessary. For a destructive, approval-gated operation with two parameters, the description covers the safety model, side effects, and the actor constraint — nothing an agent needs 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 0%, so the description carries the burden for `confirm`, and it does: default-false means preview, true means request approval. `id` is left implicit, but "a dispute record" makes its meaning evident. Not a full 5 because the description never explicitly ties the two schema fields to the described behavior by name.

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: "Delete a dispute record." That alone distinguishes it from every sibling (disputes_list, disputes_get, disputes_create, disputes_update) without needing to name them.

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

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

Clearly explains the two-mode workflow: without confirm=true it is only a preview, with confirm=true the person is asked to approve. It also states a hard constraint — the assistant cannot approve on the person's behalf — which is exactly the kind of guidance that prevents misuse. It stops short of saying when deletion is preferable to alternatives, but no sibling is a plausible substitute for deletion.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds a content preview (letters written, history, due date) that helps an agent judge whether this call returns what it needs, but says nothing about the identifier requirement, not-found behavior, or size of the returned record.

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 compact sentence with the resource front-loaded and the value proposition (what the record contains) immediately after. No filler, though it is a fragment rather than a full sentence.

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

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

An output schema exists, so return values need not be spelled out, and annotations cover the read-only profile. For a one-parameter lookup tool the description is close to sufficient; the only missing piece is any statement about the required identifier.

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

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

Schema coverage is 0% for the single required `id` parameter, so the description carries the burden and only implies that one dispute is identified, without stating that `id` is a dispute identifier or its format. The parameter name is largely self-explanatory, which keeps this from being a serious gap.

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

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

States a specific retrieval of 'the full record for one dispute' and enumerates the content (details, due date, letters written, history), which distinguishes it from the list-style sibling disputes_list. It never names a sibling outright, so differentiation is inferred from the singular framing rather than stated.

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

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

There is no explicit guidance on when to call this versus disputes_list, disputes_deadlines, or disputes_update, and no preconditions or exclusions are given. The only signal is 'one dispute', which weakly implies single-record retrieval by identifier.

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 and openWorldHint, so safety is covered; the description adds real behavioral context by disclosing the sort order (newest first) and the paging convention (feed the response's next_offset back as offset). It stops short of stating page-size behavior or default limits.

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 core purpose and ordering front-loaded, then filters, then paging. No filler and nothing repeated from the schema verbatim.

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

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

With an output schema present, return values need not be explained, and the description covers purpose, filters, and pagination adequately for a four-parameter read-only tool. The only notable omission is the limit parameter and its interaction with paging.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It touches status, party_type, and offset, but says nothing about limit, does not clarify what party_type values represent, and gives no guidance on enum choices, so compensation is only partial.

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?

Starts with a specific verb+resource ("List disputes") and adds ordering ("newest first"), which reads clearly as a collection endpoint distinct from the singular sibling disputes_get. It does not explicitly name or contrast with siblings, so it stays just shy 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?

Filtering by status or party_type and paging via offset are presented as the intended usage, which implies when to reach for this tool versus disputes_get. However, there is no explicit statement of when to use this over disputes_deadlines or other dispute siblings, leaving routing 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 non-read-only, non-destructive, non-idempotent, so the safety burden is light. The description still adds real value beyond them: every change is recorded in history (audit trail) and setting status to 'sent' without a date defaults to today.

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

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

Three short sentences, front-loaded with the core actions and followed by the two behavioral rules that matter. 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?

With annotations covering the mutation profile and an output schema present, the description sufficiently covers what the tool does and the one surprising default. It could be slightly more complete by noting that only `id` is required and that unspecified fields are left untouched.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden and largely does: it maps status, sent_date, and note to concrete effects and supplies a non-obvious default rule for sent_date. It never mentions the required `id` or enumerates the status values, leaving small gaps.

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 ("Change") plus concrete resources: status, sent date, note on a dispute. It is clearly the mutation counterpart to disputes_create/delete/get/list, though it does not name those siblings explicitly.

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

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

Usage is implied by the field list (use this to modify an existing dispute rather than create one), but there is no explicit when-to-use/when-not guidance or pointer to siblings such as disputes_create or disputes_delete.

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 state readOnlyHint=false, destructiveHint=false, idempotentHint=false, and the description is consistent with a file-writing operation. It adds real behavioral context that annotations cannot: the letter contains hand-fillable placeholders for name/address/signature, and the 'Not legal advice' caveat. It omits what an agent most needs for a non-idempotent writer: where the file is written and whether repeat calls overwrite or accumulate files.

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

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

Four short sentences, purpose stated first, parameter coaching second, disclaimer last; nothing is padded. Density is appropriate for a 7-parameter tool, though the parameter tips could be tightened into one clause.

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

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

An output schema exists, so return-value explanation is correctly omitted, and the placeholder caveat covers the biggest interpretive risk. Still incomplete for a mutation tool: the destination/location of the text file and the distinction between the two template values are missing, alongside the undocumented item_description and reason parameters.

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

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

With 0% schema description coverage, the description must carry parameter meaning, and it only does so for part of the surface. agency_key, recipient_name and dispute_id are explained with concrete semantics, but item_description, reason and recipient_address receive no explanation at all, and the template enum's two values (cra_dispute, furnisher_dispute) are not distinguished beyond 'fixed template'.

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 names a specific verb and resource plus the output medium: 'Write a dispute letter from a fixed template to a text file.' That is far more than a restatement of the name and lets an agent distinguish this from a template-listing sibling. It stops short of explicitly naming or contrasting letters_templates, so not 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?

'For a credit agency pass agency_key (equifax, experian, transunion) or recipient_name' and 'Pass dispute_id to attach the letter to a dispute record' give conditional guidance on choosing inputs. However, nothing states when to call this versus letters_templates, or what happens if neither agency_key nor recipient_name is supplied. Usage is implied by the parameter coaching rather than declared.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered structurally. The description adds that this is prerequisite context for letter generation, which is useful, but says nothing about response size, whether data is bundled or paged, or how fresh the contact details are.

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 no filler, and the imperative 'Read this before generating a letter' is placed last where it acts as a call to action. The noun-list opening is slightly dense but every item is informative.

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

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

An output schema exists, so return-value details are not the description's burden, and the tool has no parameters to document. The one gap is that it doesn't hint at the shape or volume of the bundled data, but for a zero-arg reference fetch with an output schema this is adequate.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-arg tool applies. The description correctly implies no inputs are required by framing it as a fetch of existing reference data.

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 enumerates the exact resources returned: letter templates, agencies with verified contact details, and the disclaimer. It is clearly distinguishable from the sibling letters_generate (which produces output) since this one is framed as reference data to read first. It lacks an explicit verb like 'retrieve/list', but the enumerated content makes the purpose 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?

'Read this before generating a letter' gives explicit sequencing relative to letters_generate, which is the actionable guidance an agent needs. It does not state when-not to call it or mention alternatives, so it falls short of a full 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered by structured data, not the description. The description contributes the useful nuance that this is a discovery/overview call with an optional drill-down, but says nothing about response shape, cost, or whether module settings include sensitive values.

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 no filler, and the drill-down instruction is placed second where it belongs. The first sentence is a noun list lacking a verb, which slightly weakens front-loading but costs little in length.

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

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

An output schema exists, so return values need not be described. For a discovery tool whose only parameter is a module name, though, the description never tells the agent how to obtain valid module names — a meaningful gap for a one-parameter lookup where the caller must supply an arbitrary string.

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

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

Schema description coverage is 0% and the single parameter has no enum, so the description carries the full burden. It does explain the parameter's effect (a module name yields that module's full settings list) and implies behavior when omitted; the notable gap is that no valid module names or format are given.

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 reads as a comma-separated list of content nouns (modules on, tool descriptions, data storage, skills, disclaimer) without a clear verb, so the action is implied rather than stated. It is distinguishable from siblings like disputes_list and letters_generate because nothing about disputes or letters appears, but the agent must infer that this is a meta/discovery endpoint rather than a data 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?

'Pass a module name for its full settings list' implies the no-argument vs. with-argument split (overview vs. detail), which is useful context. However, there is no statement of when to call this versus any alternative, no prerequisite info, and no guidance on where to find valid module names.

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