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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the mutation nature is known. The description adds no extra behavioral context (e.g. whether creation is reversible, idempotency, or side effects). It does not contradict annotations.

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

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

The description is a single brief sentence, which is concise and easy to parse. However, it is under-specified: it does not earn its place by conveying necessary guidance because it omits parameter semantics and usage direction.

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

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

Given the tool has 5 parameters with 0% schema coverage and requires 3 fields, the description is grossly incomplete. An agent cannot correctly call this tool without understanding parameter purpose or valid values, even though an output schema exists.

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%, meaning parameters like name, balance, account_type, account_subtype, and include_in_net_worth are not documented in the schema text. The description does not compensate: it provides no explanation of what these parameters mean or how to choose valid values, even though required fields exist.

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

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

The description clearly states the action ('create') and the resource ('manual Monarch account'), distinguishing it from other account-related tools. However, it does not explicitly differentiate itself from sibling tools, though no competing 'create' tool exists among the siblings.

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

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

No guidance is provided on when to use this tool versus alternatives, prerequisites, or context such as what constitutes a 'manual' account. The description merely states the action without any usage context.

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 indicate this is a non-read-only, non-idempotent write, so the description does not contradict them. However, it adds no behavioral context beyond that: no mention of whether account balance is updated, whether an external sync may be triggered, or whether creating a transaction is reversible. With annotations present, a brief statement of side effects would have justified a higher score.

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 one short sentence with no filler, and it front-loads the action. Its brevity is a strength, though it is so terse that it misses opportunities to convey parameter semantics or side effects. This earns a high conciseness score, not a completeness score.

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 7 parameters (5 required), a balance-update flag, and no parameter descriptions in the description, the definition is under-specified for correct invocation. An agent still needs to know amount sign/format, which getters supply account_id/category_id, and how update_account_balance behaves. The output schema and annotations help with return values and safety, but not with these input-side 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 only 29%, so the description would need to compensate, but it mentions no parameter meanings. Only the schema documents date format and category_id as a Monarch ID; amount, account_id, merchant_name, notes, and update_account_balance are left without explanatory context. The phrase 'in an account' hints at account_id, but it does not add real semantic value.

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 clear verb ('Create') and resource ('manual transaction') and identifies the scope ('in an account'), which separates it from get/update/delete transaction siblings. It does not list fields or outcomes, but the core purpose is unambiguous. A 4 reflects this clarity without extra differentiating 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?

No guidance is given about when to choose this tool over update_transaction, delete_transaction, or imported transaction flows. The word 'manual' vaguely implies a user-entered transaction, but there are no alternatives, exclusions, or prerequisites. This leaves the agent to infer usage 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?

The annotations already signal that this is a write operation (readOnlyHint=false) and non-destructive. However, the description does not add any behavioral context beyond the bare fact of creation—no mention of permissions, duplicate handling, or what happens if the referenced group does not exist. With annotations present, the bar is lower, but no extra context is provided.

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 a single, tight sentence with no redundant words. It states the core purpose immediately and nothing else, which is appropriate for such a simple 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 tool with five parameters and two required ones, the description is underpowered. It does not mention that group_id must reference an existing group, how to obtain valid group IDs, or any constraints among optional parameters. Although an output schema exists, the lack of parameter semantics and usage guidance makes this inadequate for confident 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 description coverage is only 20% (only rollover_start_month has a description), and the tool description itself explains none of the five parameters. It does not clarify relationships like rollover_enabled requiring rollover_start_month, nor what icon expects. The description completely fails to compensate for the low schema coverage.

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 ('Create') and identifies the resource ('category') and its placement ('in an existing category group'), making it clear what the tool does. It is distinct from sibling tools like delete_transaction_category or create_transaction_tag, though it could be slightly clearer that the category is a transaction-specific category.

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 provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. It implies that a category group must already exist, but does not state this explicitly or point to related tools like get_transaction_category_groups.

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

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

The description reads 'Create a reusable transaction tag,' which adds only a semantic hint about reuse but does not disclose behavioral traits beyond what the annotations already provide. The annotations correctly indicate a non-read-only, non-idempotent, non-destructive operation, and the description provides no additional behavioral context such as uniqueness constraints, side effects, or error conditions. The description does not contradict the annotations, but it also adds little beyond them.

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 a single sentence that is front-loaded with the core action and subject. It contains no filler or repetition, though its brevity borders on under-specification. Structurally it is acceptable and efficient given the expectation that the schema and annotations carry additional detail.

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 is present, which reduces the need to document return values the description itself does not explain the broader context of the tool, such as the meaning of 'reusable' (whether it can be assigned to multiple transactions), the expected naming convention, or the relationship to set_transaction_tags. For a creation tool with two parameters, the description provides the minimum viable context but misses the kind of contextual links that would help an agent integrate it into a multi-step workflow.

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 color parameter already has a schema description ('Hex color such as #4F46E5'), so its meaning is covered. The name parameter has only a minLength=1 constraint and no description, leaving ambiguity about what constitutes a valid or expected name. The tool description does not compensate for this gap; it does not explain the format, uniqueness, or role of the name parameter. With 50% schema coverage, the description should have resolved the missing coverage for name but does not.

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 clear, specific verb+resource ('Create a reusable transaction tag') and differentiates itself from sibling tools like get_transaction_tags and set_transaction_tags by its action and resource type. However, it leans heavily on the tool name itself; the value-add is modest but sufficient to identify the tool's purpose and scope.

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?

No guidance is provided on when to use this tool versus alternatives such as create_transaction_category or set_transaction_tags. There is no mention of prerequisites (e.g., tags must exist before being applied to transactions), no examples, and no indication of when creating a tag is the right step in an agent workflow. The description leaves all usage decisions 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 disclose destructive behavior (destructiveHint=true), non-read-only status (readOnlyHint=false), idempotency, and open-world effects. The description simply confirms deletion without adding extra context such as irreversibility, cascading effects, or permissions. No contradiction with annotations, but no additional behavioral transparency.

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 a single, front-loaded sentence with zero wasted words. It directly conveys the action and target resource, making it efficient and easy to parse.

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

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

The tool is simple with one required parameter, annotations cover destructive/idempotent behavior, and an output schema exists. The description is adequate for basic invocation, but it omits potentially useful context such as whether deletion is permanent or affects related data, which would make it fully complete.

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

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

The input schema fully documents account_id with a description referencing get_accounts, and schema description coverage is 100%. The description's 'by ID' adds no additional semantic 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 verb ('delete') and resource ('Monarch account') and the identification method ('by ID'), making the action unambiguous. It clearly distinguishes from sibling tools like create_manual_account and update_account, which are lifecycle operations.

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

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

The description does not specify when this tool should be used instead of alternatives such as update_account or create_manual_account. It gives no conditions, prerequisites beyond having an ID, or exclusions, leaving usage 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, readOnlyHint=false, and idempotentHint=true, so the candidate's destructive and unsafe writing nature is well-established. The description itself adds no further behavioral context—it doesn't mention irreversibility, cascading effects on splits, or error conditions—but it doesn't contradict the annotations either (delete aligns with destructive=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?

The definition is a single, front-loaded sentence with no waste. It conveys the verb, resource, and required input in the smallest useful amount of text, appropriately sized for a one-parameter destructive operation.

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 simplicity (1 param) and the strong annotations (destructive, non-readonly, idempotent) plus an output schema, the description is adequate for a basic call. The main missing context is peripheral, like whether specifying transactions auto-deletes their splits or any side effects on linked categories; these are not critical for a single-id delete but would be nice.

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% (transaction_id is fully described as 'Monarch transaction ID'), so the baseline of 3 applies. The description adds no parameter semantics beyond the obvious 'by ID' mapping; it does not clarify format, provenance of the ID, or validation rules, but the rich schema compensates.

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 ('delete'), a concrete resource ('transaction'), and the mechanism ('by ID'), which clearly separates it from get_transaction, update_transaction, and create_transaction among the siblings. It also avoids tautology since 'by ID' adds meaningful scope beyond the tool name and title.

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 contains no guidance on when to use this tool over alternatives like update_transaction or delete_transaction_category. No context about typical workflows, prerequisites (e.g., needing a valid transaction ID first), or consequences is given, so an agent has nothing to ground the selection decision on.

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 flag destructiveHint=true, so the destructive nature is covered. The description adds useful context by mentioning the optional move of transactions to another category, but it does not disclose what happens to the transactions when move_to_category_id is omitted. That omission leaves an important behavioral consequence unresolved.

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 a single clean sentence with no filler or repetition. It front-loads the core action and immediately adds the most important optional behavior, which is exactly as concise as it needs to be.

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 tool with an optional migration parameter, the description should explain the consequence of not providing move_to_category_id. The output schema covers return values, and annotations cover safety, but the fate of transactions when no target category is supplied remains unclear, which is a significant gap for an AI agent deciding whether the call is safe.

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%, giving each parameter a basic description. The description adds meaningful semantics by explaining that move_to_category_id is used to move the category's transactions to another category before deletion, which is not fully captured by the schema's bare 'Monarch category ID' 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?

The description uses a specific verb and resource: 'Delete a category', which clearly distinguishes it from sibling tools like delete_transaction or update_transaction. The added clause about optionally moving transactions to another category further clarifies the tool's exact responsibility 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 implies when to use the tool and clarifies the optional migration behavior, but it does not explicitly state when this tool should be preferred over alternatives or what to do when a category has transactions. There are no explicit exclusions or alternative-tool routing, so the guidance is inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description has a low burden. The phrase 'complete available daily balance history' adds a small amount of context about the data's scope, but does not disclose behaviors like pagination, date filtering, or account type restrictions.

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 a single, tight sentence that conveys the key facets: completeness, granularity, and scope. There is no filler or redundancy, making it an ideal length for quick comprehension.

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 simple one-parameter schema, the presence of an output schema, and the rich annotation set, the description is largely sufficient for making a correct call. However, the lack of differentiation from closely related sibling tools slightly undermines an otherwise complete definition.

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 parameter account_id is documented as 'Monarch account ID from get_accounts'. The description adds no semantic detail 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 clearly states a specific verb ('Get') and resource ('daily balance history for one account'), making the tool's core purpose obvious. However, it does not differentiate itself from sibling tools like get_recent_account_balances or get_net_worth_history, leaving the agent to infer distinctions from the name alone.

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?

No guidance is provided about when to choose this tool over siblings such as get_recent_account_balances or get_net_worth_history. The single-account scope is implied, but without explicit exclusions or alternatives, the agent is left to guess based on tool names.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no extra behavioral context such as return format restrictions, pagination, or required prior steps. It does not contradict the annotations, but it also does not enrich them with additional behavioral traits.

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 a single sentence with no redundant words. It front-loads the core action and object, making it easy to parse and directly actionable for an agent.

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 simple single-parameter read-only nature, an output schema exists, and annotations cover safety, the description is largely complete. The only minor gap is not explicitly stating that the account must already exist or that it should be an investment account, though this is inferable from the description and parameter reference to get_accounts.

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 single parameter account_id is fully documented in the schema as 'Monarch account ID from get_accounts'. The tool description itself adds no further parameter semantics, but with full schema coverage 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 'Get securities and positions for one investment account' clearly states a specific verb (Get) and resource (securities and positions) with a scoped target (one investment account). This distinctly differentiates it from sibling tools like get_account_history or get_recent_account_balances, making the tool's 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?

The description implies usage when needing holdings for a specific investment account but does not explicitly state when to use it versus alternatives, nor does it mention exclusions or prerequisites. The context of needing an account ID is implied by 'one investment account' and the parameter description, but no direct guidance is given beyond the core function.

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. The description adds behavioral context by specifying that compact output always includes account IDs, balances, institutions, and freshness. This goes beyond annotations and helps the agent know what the default response 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?

Two sentences, both high-value. The first sentence lists scope, the second clarifies output invariants. No filler, front-loaded with the resource name and types.

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 one optional parameter and a full output schema provided, the description covers the essential behavioral promise. An agent can invoke it correctly without additional clarification.

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% for the single parameter 'detail', which has an enum and a description explaining compact vs full. The tool description mentions 'Compact output' which aligns with the parameter default but adds no new meaning. Baseline 3 is appropriate because the schema carries the semantic load.

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?

Description states a specific verb ('List') and resource ('Monarch accounts'), enumerates the account types covered (bank, credit, investment, loan, manual), and notes the compact output includes key fields. This clearly distinguishes it from siblings like get_account_holdings or get_institutions.

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

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

The description implies when to use this tool: to get a list of all accounts with balances and institutions. It doesn't explicitly state alternatives or when not to use it, but the context is clear given the sibling list. There are no exclusions or alternative routing, so it earns a 4 rather than 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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds grouping by account type and timeframe, but these are largely inferable from the tool name/title and the parameter enum. No extra behavioral details such as period boundaries, timezone handling, or data availability are disclosed.

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 sentence with no filler or redundancy. It is front-loaded with the action and resource, and every word adds value.

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

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

The annotations and output schema cover safety and return structure, and the description states the core capability. However, usage guidance relative to siblings and the precise semantics of start_date are missing, so an agent could misinvoke the tool when a specific date context matters.

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 50%: only start_date has a description in the schema, and it just says 'Date in YYYY-MM-DD format'. The tool description clarifies 'timeframe' via 'monthly or yearly' but gives no semantic context for start_date (e.g., whether it is the start of the period, an exact date, or an as-of date), leaving an important parameter ambiguous.

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

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

The description states a specific verb and resource: get monthly or yearly balance snapshots grouped by account type. This is clear and distinct from sibling tools like get_recent_account_balances, though it does not explicitly name an alternative.

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

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

The description implies its own use case (retrieving balance snapshots by account type at monthly/yearly granularity) but gives no explicit when-to-use or when-not-to-use guidance, nor mentions any sibling alternatives. An agent can infer the basic purpose but not compare it with related history/recent 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is fully known. The description adds no extra behavioral details, but also does not contradict 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?

One clear, front-loaded sentence that states the resource and its scope. No wasted words.

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 zero parameters, an output schema present, and comprehensive annotations, the description provides all essential context an agent needs to invoke the tool correctly.

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

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

The tool has zero parameters, so the baseline is 4 per the rubric. The description correctly implies no inputs are needed; nothing more is required.

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

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

The description clearly states the tool lists valid Monarch account types and subtypes, scoped to manual-account operations. The verb 'List' and specific resource make it distinct from sibling tools like get_accounts.

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 provides clear context — this is for manual-account operations — which signals when an agent would need it. It does not explicitly exclude alternatives, but given its unique purpose, the context is sufficient.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context: the result is broken down by category and month, and there is a default date window when no dates are supplied. It does not contradict the annotations.

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

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

Two sentences contain no filler. The first sentence communicates the output substance, and the second gives the most important invocation default. Every element 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 low-complexity, read-only tool with an output schema, the description is nearly complete. It names the budget measures, grouping dimension, and default date behavior. Minor ambiguity about how start_date and end_date behave when only one is supplied prevents a higher score.

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

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

The schema only documents the date format and optionality. The description adds meaningful cross-parameter semantics by explaining that omitting both dates selects the previous-through-next-month window. It does not fully explain single-date behavior or range inclusivity, but the schema and descriptive parameter names carry much of the burden.

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 tells an agent exactly what is returned: planned, actual, remaining, and rollover amounts grouped by category and month. This is far more specific than the tool name and clearly separates it from the account, transaction, and cashflow getter siblings.

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

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

The description gives a clear retrieval context and practical invocation guidance by saying 'Omit both dates for the previous through next month.' It does not explicitly name alternatives or exclusion cases, but the intended role of the tool is clear enough for an agent to select it correctly.

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, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds one useful behavioral nuance—the default current-month scope when dates are omitted. It does not add excessive detail, which is appropriate given the strong 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?

Single sentence, front-loaded with the core output and grouping model, followed by a compact usage note. No filler or repetition; all content earns its place.

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

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

With only two optional inputs and an output schema present, the description covers the essential invoke semantics: what is returned, how it is grouped, and how to request the current month. Nothing needed for daily invocation is missing.

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

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

Schema descriptions for both parameters only provide 'Date in YYYY-MM-DD format,' with 100% coverage, so the baseline is 3. The description adds semantic value by clarifying the default behavior when both are omitted (current month) and implying a date range when provided, which the schema does not communicate.

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

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

The description states a specific verb and resource: 'Get income and expense aggregates grouped by category, category group, and merchant.' This clearly differentiates it from sibling tools like get_cashflow_summary (which implies a summarized view) and get_transactions (which returns raw transactions). An agent immediately knows what object and grouping it will receive.

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 offers parameter usage guidance ('Omit both dates for the current month') but no explicit instruction on when to select this tool versus alternatives such as get_cashflow_summary or get_transactions. It lacks a when-to-use or when-not-to-use statement, leaving tool selection 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?

注释已经提供了readOnlyHint、openWorldHint、idempotentHint等安全属性。描述额外补充了“exact”聚合和“省略两个日期表示当前月”的行为，这些是注释未涵盖的有价值信息。没有矛盾。

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?

两句话简洁明了，第一句定义功能，第二句说明日期行为，没有任何冗余内容。信息密度高且易于理解。

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?

对于仅有两个可选参数的简单工具，描述配合全面的注释和输出模式，已经提供了调用所需的所有关键信息。日期范围语义和精确聚合都清晰，无需额外解释。

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?

输入模式中两个参数都有详细格式描述（100%覆盖），描述进一步解释了省略两个日期时的语义（默认为当前月），这为参数添加了超出模式本身的信息。

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?

描述明确说明了工具的功能：获取特定日期范围内的收入、支出、储蓄和储蓄率的精确汇总。动词“Get”和资源“cash flow summary”都清晰。但没有与兄弟工具（如get_cashflow）进行区分，所以未达到最高分。

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?

描述提供了使用指导：“Omit both dates for the current month”说明了何时省略参数，但没有明确说明何时应使用此工具而非替代工具（如get_cashflow）。上下文隐含但未明确排除或推荐替代方案。

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 tool as read-only, idempotent, and non-destructive, so the description does not need to repeat those. It adds context about returning credentials and connection state, which is useful, but there is no mention of pagination, ordering, or potential sensitive data handling.

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 a single concise sentence that covers the entire scope of the tool. No filler or redundancy, and it is appropriately sized for a parameterless read-only list operation.

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 zero parameters, a rich set of annotations, and an output schema, the description provides sufficient scope. It could mention edge cases like empty results or credential refresh status, but the essentials are present for a simple listing tool.

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

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

The tool has zero parameters, so per the rubric the baseline is 4. The description correctly does not attempt to explain parameters that do not exist.

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

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

The description clearly states the tool lists linked institutions, credentials, accounts, and connection state. The verb 'List' and the specific resources make the purpose clear, though it does not explicitly differentiate from sibling tools like get_accounts.

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?

No guidance is provided on when to use this tool versus alternatives. The description does not mention any exclusions or alternatives, leaving the agent to infer usage from the tool name alone.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and side-effect expectations. The description adds the behavioral trait of 'daily aggregate balances' but does not describe pagination, required date ranges, or response shape beyond what the output schema likely provides. No contradiction with 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?

A single, tight sentence that leads with the action and object, then states the aggregate scope and filter. No filler, no repetition of schema details that are already present.

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 simple read-only nature, the presence of an output schema, and annotations covering safety, the description is adequate for an agent to decide when to call it. Minor gaps remain about whether date range is required and how the aggregated balances are denominated or structured, but these are not critical for a basic 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 description coverage is 67% with start_date and end_date documented as 'Date in YYYY-MM-DD format'. The description explicitly mentions 'optionally filtered by account type', which gives meaningful semantic context to the undocumented account_type parameter, clarifying its purpose and optionality.

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?

Description starts with a specific verb ('Get') and a resource ('net worth history') with clear scope ('daily aggregate balances across accounts') and an optional filter. It is easily distinguishable from sibling tools like get_account_history or get_recent_account_balances by emphasizing cross-account aggregation.

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

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

The description implies a clear use case: retrieving aggregated daily balances across accounts, which contrasts with per-account history tools. It does not explicitly state when not to use it or name alternatives, but the context of 'across accounts' and 'optionally filtered by account type' provides enough guidance for an agent to select it over more granular 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 cover read-only and idempotent behavior, so the bar is lower. The description adds useful scoping context: it returns daily balance arrays for every account and is bound to a start date. However, it does not disclose behavior such as default date range if start_date is omitted or response limits, but annotations cover the main side-effect concerns.

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 a single clear sentence that front-loads the operation and scope. There is no filler or repetition of information already in 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 one-parameter read-only tool with an output schema, the description is almost complete. It tells the agent exactly what data to expect and the date anchoring. The only minor gap is behavior when start_date is omitted (required: 0), but 'recent' in the title and the option to explicitly provide a date mitigate this uncertainty.

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 for the single parameter is 100%; the schema already documents start_date as a YYYY-MM-DD date with validation. The description's 'starting on a date' reinforces the parameter's role but adds no new format or semantics beyond the schema. 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 states a precise operation: 'Get daily balance arrays for every account starting on a date.' This clearly differentiates the tool from siblings like get_account_holdings or get_account_history by focusing on daily balance arrays across all accounts. The resource and scope are 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?

The description provides no when-to-use guidance, alternatives, or exclusion criteria. Sibling tools exist (e.g., get_account_history, get_net_worth_history), but the text does not indicate when to choose this over them. Usage must be inferred entirely from the description.

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 the read-only/non-destructive nature, so the description does not need to repeat that. It does add a useful default behavior ('Omit both dates for the current month'), but it leaves the meaning of 'upcoming' under-defined, especially in relation to arbitrary date ranges and whether past intervals are valid. This ambiguity raises the bar for behavioral disclosure.

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

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

The description is two sentences and 17 words. It front-loads the resource and scope, then gives the default-usage hint, with no redundant repetition of schema or annotation 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?

For a simple two-optional-parameter read tool, the description gives enough for the most common cases (all dates omitted → current month; both dates supplied → a range). However, it does not clarify valid combinations if only one date is provided, nor does it precisely define how 'upcoming' interacts with past date ranges. These gaps are significant enough that an agent could make a valid-looking but semantically incorrect 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 schema param descriptions only say 'Date in YYYY-MM-DD format', giving format but no meaning. The description compensates by explaining that omitting both dates defaults to the current month, which gives an important semantic for optional parameters. It still does not specify what happens when only one date is provided, but the start/end names are reasonably self-explanatory.

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

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

The description clearly identifies the action ('Get'), the resource ('recurring transactions'), and enumerates the specific types covered: bills, subscriptions, transfers, and income. It is distinct from the sibling get_transactions tool because of the 'recurring' and 'upcoming' qualifiers, so an agent can tell what it does 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?

The description never explicitly states when to use this tool versus siblings like get_transactions, nor does it mention any exclusions or alternatives. The scope is implied by the word 'recurring' and by the categories listed, and the 'omit both dates' sentence is a parameter-level instruction, not a tool-selection guideline.

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 provide strong safety/side-effect signals (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description adds no additional behavioral detail. The only added value is clarifying it checks completion. No contradictions with 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?

A single, direct sentence that front-loads the core purpose. There is no filler or irrelevant detail, and it is appropriately sized for the tool's simplicity.

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

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

The description, combined with annotations and output schema, covers the basics: what it checks and that it is safe/idempotent. However, it lacks important context about the behavior when no account_ids are provided (the parameter is optional in schema) and how to interpret the result in the broader refresh workflow. More guidance on polling or failure handling would improve completeness.

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% (despite the inline parameter description noting IDs come from get_accounts). The description does not compensate for this by explaining how account_ids impact the check. The parameter itself is self-explanatory, but the description fails to add meaning beyond the bare schema.

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

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

The description states a specific verb ('Check') and resource ('prior institution refresh') that clearly identifies the tool's purpose. It distinguishes itself from sibling tools like refresh_accounts by focusing on checking status rather than initiating a refresh. However, it could more explicitly state what the result is used for.

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 no explicit guidance on when to use this tool versus alternatives. It implies that it should be used after a refresh is initiated, but it does not mention prerequisites (e.g., having initiated a refresh) or what to do if a refresh is in progress. This leaves the agent to infer usage context.

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 fully covered structurally. The description adds value beyond annotations by disclosing the breadth of data returned (plan, entitlement, trial, payment-source) — exactly the kind of context that helps an agent set expectations for a single request.

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, well-formed sentence that front-loads the verb and resource, then lists the specific metadata dimensions. Every clause earns its place; there is no filler, boilerplate, or repeated structured 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?

For a zero-parameter, read-only getter with an output schema present, the description is complete. It tells the agent what data the call returns, and the annotations + output schema carry the behavioral and return-format burden. Nothing an agent needs to select and call this tool 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?

The tool takes zero parameters, so the schema coverage is 100% with nothing to document. The description correctly adds no parameter syntax. With no parameters, this is the baseline score of 4 — there is nothing more the description could contribute.

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 ('Get') and resource (Monarch subscription) and enumerates the return content — plan, entitlement, trial, and payment-source metadata. This clearly differentiates it from all sibling tools, which cover accounts, transactions, budgets, and cashflow, none of which overlap with subscription data.

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 purpose implies the use case — retrieving subscription/plan metadata from Monarch — but the description offers no explicit guidance on when to choose this over alternatives or any conditions/exclusions. With no directly competing sibling (all siblings are in other data domains), the absence of exclusions is minor, but the guidance is still implied rather than stated.

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

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

The description adds 'full details' but otherwise the read-only, idempotent, non-destructive behavior is already declared by annotations. No contradiction, and the description does not need to repeat annotation-provided safety traits.

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 a single, direct sentence with no filler. It immediately states the action and scope, making it easy to parse quickly.

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 low complexity, one well-documented parameter, rich annotations, and the presence of an output schema, the description is sufficient for an agent to select and invoke the tool correctly without additional return-value details.

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

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

The input schema fully describes the only parameter as 'Monarch transaction ID' with 100% schema description coverage. The description adds no additional parameter meaning, so baseline 3 applies.

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

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

The description uses a specific verb and resource: 'Get full details for one transaction.' It clearly distinguishes itself from the plural 'get_transactions' and other transaction-related siblings by emphasizing a single transaction and full details.

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

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

The singular 'one transaction' provides clear contextual signal that this tool is for individual lookups, differentiating it from get_transactions. It does not explicitly mention alternatives, but the scope is evident from the description and naming.

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 read-only, idempotent, and non-destructive, so the description does not need to restate that. The description adds that the results include IDs and group membership, which provides a little context beyond safety traits, but it does not describe ordering, pagination, or any side effects. This is consistent with the annotations; no contradiction exists.

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

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

The description is a single, front-loaded sentence that states the exact action and data included. It is concise, contains no fluff, and uses every word to convey the tool's function.

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

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

For a zero-parameter, read-only tool with an output schema and annotations that already establish safety, the description is largely complete. However, the presence of the sibling get_transaction_category_groups creates a potential ambiguity: an agent might wonder whether this tool returns group or categories themselves. The description does not explicitly clarify that distinction, which makes it a 4 rather than a full 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?

The tool takes zero parameters, so there are no parameters to explain. The baseline for 0 parameters is 4, and the description does not need to compensate for missing schema documentation. It adds nothing about parameters, but none are needed.

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 clear verb and resource: 'List all transaction categories' and adds the scope 'with IDs and category groups.' It is precise and distinct from the related transaction‐categories tool, but it does not explicitly name the sibling get_transaction_category_groups to clarify the difference, so it misses the full 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?

There is no guidance on when to use this tool versus alternatives or when not to use it. The description gives no context about selection among the many list/category tools in the 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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds minimal behavioral context by stating 'all' (scope) and 'with IDs' (return content), but does not disclose details like ordering, pagination, or response structure. It does not contradict annotations.

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

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

The description is a single, tightly worded sentence that immediately states the purpose and key output detail. No unnecessary words or 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?

For a parameterless list-all tool with an output schema, the description is sufficient. It conveys the full action and the primary return field (IDs), while annotations cover safety and output schema defines the response shape.

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

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

The tool has zero parameters, so there is nothing for the description to explain about inputs. Schema coverage is 100% vacuously, and the baseline for 0 params is 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?

The description clearly identifies the action (List) and resource (transaction category groups), and specifies that it returns IDs. It does not explicitly contrast with the sibling get_transaction_categories, but the resource name 'category groups' is distinct enough to avoid confusion.

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?

No guidance is provided on when to use this tool versus alternatives like get_transaction_categories or get_transaction_tags. There is no mention of scenarios, exclusions, or how this differs from other list operations.

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, covering the safety profile. The description adds useful context about 'exact pagination' and compact result formatting, which is more than nothing. However, it does not disclose behaviors like error handling, rate limits, or the meaning of pagination beyond what the schema parameter descriptions already imply.

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 consists of two concise, front-loaded sentences with no filler. The primary action is stated first, and the result format is a reasonable second sentence. Every word 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?

Given the tool's complexity (16 optional parameters, multiple filter types, pagination, and a large sibling family), the description is far too sparse. Even with an output schema present, the agent lacks guidance on how to construct effective searches, what 'exact pagination' implies, or how this tool relates to get_transaction. It does not meet the needs of a complex search endpoint.

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 only 19% schema description coverage and 16 parameters, the description carries a heavy burden to explain parameter meaning, but it only mentions the 'compact' detail mode indirectly. It does not clarify how search, date ranges, account_ids, tags, or the various boolean filters behave, leaving significant ambiguity that the schema does not resolve.

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 specific verbs ('Search and filter') and a clear resource ('transactions'), and it differentiates itself from sibling tools like get_transaction (single transaction) and get_recurring_transactions by explicitly covering general search and filtering. It also adds concrete detail about result content ('Compact results retain transaction, account, category, merchant, and tag IDs'), making the purpose unmistakable.

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

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

The description does not state when to use this tool versus alternatives such as get_transaction or create_transaction. There are no explicit conditions, exclusions, or comparisons to sibling tools. While 'search and filter' implies a query use case, no guidance is given for selecting among the many transaction-related 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?

The available annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's 'Get' is consistent with these flags. However, the description adds no extra behavioral context, such as behavior when a transaction has no splits, error conditions, or authentication expectations. It meets the baseline for a read-only operation.

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

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

The description is a single sentence, free of filler, and clarifies the title by adding 'legs' and 'for one transaction'. It is appropriately concise for a simple one-parameter tool, though it could still be slightly richer without losing focus.

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, one-parameter tool with strong annotations and an output schema present, this description is largely sufficient for an agent to invoke it correctly. The main gap is that domain-specific terminology ('split legs') is not explained and edge cases like a transaction with no splits are not mentioned, so it is not fully comprehensive.

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 sole parameter, transaction_id, is already documented in the schema as 'Monarch transaction ID' with 100% coverage. The description does not add further context about the expected format or how it maps to the split legs. With complete schema coverage, a score of 3 is appropriate and no penalty is incurred.

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 ('Get') and resource ('split legs') scoped to one transaction, and it adds detail beyond the title by using 'legs' and specifying singular. It does not explicitly contrast it with sibling tools like get_transaction or get_transaction_categories, but the resource is distinct enough for an agent to understand what it returns.

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 guidance about when to use this tool versus related sibling tools such as get_transaction or set_transaction_splits. The description does not mention exclusions, prerequisites beyond an ID, or a complementary write tool. This is a significant gap for an agent choosing among many similar financial read 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the scope 'all' and enumerates returned fields, providing mild context, but it does not disclose behaviors like pagination, rate limits, or side effects. With annotations carrying the burden, a 3 is appropriate.

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 a single sentence that begins with the verb 'List' and immediately specifies the resource, then compacts the returned attributes into a short list. Every word earns its place with no 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?

With no parameters, read-only annotations, an existing output schema, and a description that clearly states the returned fields, an agent has all information needed for correct invocation. Absence of filter options or prerequisites is not a gap for a list-all 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?

The input schema is empty, so there are zero parameters to document; the schema fully specifies that no arguments are required. Baseline for no-parameter tools is 4, and the description adds nothing about parameters because nothing needs clarification.

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

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

The description clearly states the operation ('List'), the resource ('transaction tags'), and the fields returned ('IDs, names, colors, and usage counts'). The term 'tags' distinguishes this from sibling category tools like get_transaction_categories, leaving no ambiguity about purpose.

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 no explicit guidance on when to use this tool versus related sibling tools such as get_transaction_categories or set_transaction_tags. Usage is only implied by the tool's name and verb — an agent can infer 'use when you need transaction tags' — but there is no mention of alternatives or exclusions.

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

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

The description explicitly says the call waits for completion by default and then returns fresh account metadata, which is behavioral context beyond the readOnly/idempotent/destructive annotations. It discloses that the operation triggers an external request to linked institutions, implying a possible delay, and that omitting account_ids broadens the scope to all accounts. It does not describe poll/timeout interplay, but the presence of those parameters in the schema covers them.

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; the central behavior and the key default-scope rule are front-loaded. Every clause contributes information, making the description efficient and easy to parse.

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

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

The definition captures the triggering behavior, the default blocking behavior, and the all-account refresh case, which covers the main decisions for a 4-parameter tool with no required parameters. It leaves out any explanation of the polling parameters and does not mention what kind of errors may surface, but the output schema and numeric constraints cover much of the remaining context.

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

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

With zero schema description coverage, the description must carry parameter meaning; it explains account_ids via the omission rule ('Omit account_ids to refresh every account') and wait via 'wait for completion by default.' It gives no semantics for poll_seconds or timeout_seconds, so an agent must rely on their names and numeric constraints alone. This partial coverage justifies a middle score.

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

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

The description uses a specific verb ('Ask linked institutions') and identifies the resource (linked accounts), clearly distinguishing this from retrieval tools like get_accounts. It also states the default wait behavior and the all-account scope in the second sentence, leaving no ambiguity about what function the tool 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?

The description provides no guidance on when to choose this over alternatives such as get_refresh_status or get_accounts; it never mentions when a refresh is appropriate or when to instead read cached data. The only usage hint given is account scoping ('Omit account_ids to refresh every account'), which is parameter guidance rather than tool-selection guidance.

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 communicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the description carries a lower burden. It usefully adds that 0 clears the budget, but it does not explain how category_id and category_group_id interact or what start_date and apply_to_future affect.

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 dense sentences with no filler. The core action, the one-category-or-group constraint, and the clear-on-zero behavior are all front-loaded and each 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 tool with five parameters and only 20% schema description coverage, the description is under-specified. It does not clarify whether at least one of category_id or category_group_id is required, how start_date and apply_to_future behave, or what output can be expected beyond the provided output schema.

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

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

Schema description coverage is only 20%, and the description only meaningfully explains amount (0 clears it). It leaves amount units, start_date semantics, apply_to_future behavior, and the selection between category_id and category_group_id largely unspecified.

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?

Description states a specific verb ('Set') and resource ('monthly budget'), and adds the key constraint 'exactly one category or category group.' This clearly distinguishes it from read-only siblings like get_budgets and from the transaction/account tools.

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

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

The description gives clear usage context: this is the write operation for monthly budgets, constrained to one category or category group, and amount 0 clears it. It does not explicitly name alternatives or state when not to use it, so it misses 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 indicate the tool is not read-only, is idempotent, and not destructive to the parent. The description adds valuable behavioral context: it replaces all existing split legs, requires amounts to sum to the parent, and that an empty array removes splits. This goes beyond the annotation hints.

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 extremely concise sentences with no filler. The core action and key constraints are front-loaded, and every word adds value.

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

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

For a two-parameter mutation tool with a clear action, the description covers all necessary operational details: replacement semantics, amount summation, and how to remove splits. The output schema handles return values, and annotations cover safety/idempotency. Nothing essential is missing.

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

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

Schema coverage is only 50%, but the description compensates significantly for the 'splits' parameter by stating the summing constraint and the empty-array removal use case. It does not repeat schema descriptions for transaction_id, but that parameter is already well described 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 uses a specific verb ('Replace') and a specific resource ('all split legs on a transaction'), clearly distinguishing this from read-only tools like get_transaction_splits or other transaction updates. It is unambiguous about what the tool does.

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 clearly explains the behavior and includes a special case for removing splits via an empty array, but it does not explicitly state when to use this tool versus alternatives like update_transaction or get_transaction_splits. The usage context is implied but not contrasted with siblings.

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 indicate a non-read-only, idempotent, non-destructive write operation. The description adds meaningful behavior: the tags are entirely replaced, and passing an empty array removes all tags. This gives context beyond the annotations by detailing what 'set' means in terms of existing tag associations. It does not contradict the annotations.

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

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

The description is only two sentences, with the core action front-loaded: 'Replace all tags on a transaction.' The second sentence is a valuable edge-case note with no unnecessary words. Every component 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?

Given the small parameter set, the existing output schema, and the annotations, the description covers what an agent needs to call the tool correctly. It explains the main behavior and the special clearing behavior. It does not discuss error conditions like invalid tag IDs, but these are not essential for a typical 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 description coverage is 50% (transaction_id has a description, tag_ids does not). The description compensates by explaining the empty-array behavior for tag_ids and implying that non-empty arrays are the replacement set. However, it does not explicitly state that tag_ids entries are tag identifiers that must already exist, which could lead an agent to pass arbitrary strings. The parameter name is self-explanatory but the description could be richer.

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 the specific action: 'Replace all tags on a transaction.' This clearly identifies the verb and resource and distinguishes it from related tools such as create_transaction_tag (which adds a tag) or update_transaction (which updates other transaction fields). It also covers the key edge case of removing all tags, leaving no ambiguity about what the tool does.

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

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

The description implies that this tool is for setting the complete tag set on a transaction, and the empty-array behavior clarifies when you want to clear tags. It does not explicitly name alternatives like create_transaction_tag, but the 'replace all' phrasing makes the intended use case clear. This is strong enough for an agent to decide when to call it, though a direct comparison to a sibling would improve it.

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

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

Annotations already cover readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat these. The phrase 'Update the supplied fields' adds a light behavioral note that only specified fields are changed, but there is no mention of validation, side effects, or required permissions. No contradiction with 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?

A single sentence that is direct and front-loaded with the action and resource. No filler or redundant information, making it highly concise and easy to scan.

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

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

The presence of an output schema and annotations lightens the burden, but the low parameter coverage means an agent may not know what each field does or whether they are all optional. The description does not explain update semantics (e.g., partial vs. full replacement) or any constraints, leaving gaps for a tool with 8 parameters.

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

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

Schema description coverage is only 13% (only account_id has a description), leaving seven other parameters undocumented. The description's 'supplied fields' gives a high-level hint but does not compensate for the lack of parameter-level meaning or clarify how values like balance or account_type are interpreted.

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

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

The description clearly states the action (update) and the resource (existing Monarch account) with a specific verb and object. It distinguishes itself from sibling tools by focusing on updating supplied fields rather than retrieval or creation.

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

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

The description implies the tool is for modifying existing accounts, but it does not explicitly state when to use it versus alternatives like create_manual_account or delete_account. No exclusions or conditions are provided, so usage guidance is mostly implied.

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

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

The description reveals a critical behavioral detail beyond the annotations: it only updates the supplied fields, implying a partial update that leaves other fields untouched. This complements the annotations (readOnlyHint=false, idempotentHint=true) without contradicting them, though it does not discuss side effects or permission requirements.

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 a single sentence that front-loads the key constraint ('only the supplied transaction fields') and then lists the fields. It is concise, scannable, and contains no filler or repetition.

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

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

Given the tool's complexity (9 parameters, 1 required) and the presence of an output schema, the description provides sufficient context for an agent to make a correct call. It clarifies the update scope but does not detail return values or error behaviors; however, these are partially covered by the output schema, reducing the burden on the description.

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 schema description coverage at only 33%, the description compensates by naming all updateable fields in plain language (category, merchant, goal, amount, date, notes, report visibility, review state), mapping loosely to schema properties like category_id, merchant_name, goal_id, hidden_from_reports, needs_review. It adds semantic meaning beyond bare parameter names, though the mapping is not exact.

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

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

The description clearly specifies the action 'Update' and the resource 'transaction', then enumerates the exact fields that can be updated. This differentiates it from sibling tools like create_transaction, delete_transaction, or get_transaction, making its 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?

The description implies usage: use this when you need to modify specific fields of an existing transaction. However, it does not explicitly contrast with alternatives such as create_transaction for new transactions or delete_transaction for removals, leaving the 'when not to use' implicit.

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