Analysis — Credit funding

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

Annotations already establish the safe read-only profile, and the description adds genuinely useful behavior beyond that: one request per month of history, name-based matching because YNAB exposes no linking identifier, and explicit reporting of unmatched accounts/categories rather than silent dropping. It does not state rate-limit or failure behavior in detail, keeping it at a 4.

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 a [READ] tag and the core purpose, then the diagnostic value, then the parameter detail. Every sentence is substantive, though the two 'problems' enumeration and the parenthetical explanation of the historical-negative case run slightly long.

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

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

Output schema exists so return values need not be explained, and the description covers matching semantics, the months default/cost, and the unmatched-handling edge case. The only real gap is the undocumented `plan_id`, which slightly detracts from an otherwise complete picture for this complexity level.

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

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

Schema coverage is 0%, so the description has to carry both parameters. It fully documents `months` (default 6, one request per month, 0 to skip) including the cost tradeoff, but `plan_id` is never mentioned, leaving half the parameters undocumented in both schema and description.

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?

Names a specific analysis resource (credit card / line-of-credit funding) and enumerates exactly what it reports: what each card owes, what its payment category holds, the difference, uncovered debt, and stranded money in closed-account payment categories. The line 'two problems live here and nowhere else in YNAB's interface' cleanly separates it from siblings like analysis_overspent_history and analysis_target_funding_gaps.

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 this tool is the right one — detecting debt with no money set aside and funds stranded in a closed account's payment category — and effectively rules out other tools by stating those diagnostics exist nowhere else. It stops short of explicitly naming an alternative tool or a when-not condition, so it is a 4 rather than a 5.

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