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

Annotations only declare readOnlyHint and openWorldHint, so the description carries important behavioral disclosure. It reveals significant non-obvious traits: no pagination, up to 2000 transactions, potential incompleteness, forecast buckets in response order rather than calendar order, fixed confidence labels, partial error behavior, and metadata.transactions_truncated. This goes well beyond the annotations and is exactly the kind of context agents need.

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 well structured: a one-sentence purpose statement, a compact Args block, and then dense but relevant behavioral caveats. No sentence is wasted, and the critical limitations are grouped clearly. The length is justified by the operational importance of the caveats.

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

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

With an output schema present, return values are already documented, so the description focuses on invocation semantics. It covers parameter meaning, data limits, error behavior, truncation signaling, and provides a pointer to get_transactions for narrower detail. This is complete for safe and correct use of the tool.

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

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

Schema description coverage is 0%, so the description must compensate for all parameters. The Args section does this thoroughly for all three: lookback_months specifies the window and default, include_forecasting explains the estimate type, and verbose clarifies full budget details vs monthly totals. This adds real meaning beyond the bare schema titles.

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 opens with a specific verb and resource: 'Summarize monthly trends, category expenses, account usage, and budget data.' This clearly states what the tool does and its scope. It does not explicitly differentiate itself from sibling analysis tools like get_spending_summary, so it falls short of a perfect 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?

The description provides clear context on when this tool is appropriate, noting that it uses only one page of up to 2000 transactions and can be incomplete for larger periods. It also gives an explicit alternative: 'Fetch narrower date ranges with get_transactions for detail.' It does not fully enumerate when-not-to-use cases versus other analysis siblings, so a 4 is appropriate.

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 indicate a non-read-only, non-destructive, non-idempotent mutation, and the description's 'Create' is consistent with that. However, the description adds little beyond the tool name: 'manual account' is already in the title, and there is no disclosure of side effects, duplicate behavior, or post-creation state. The word 'manual' is a type hint, not meaningful behavioral context.

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

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

The description is a single active-voice sentence with no filler and a clear front-loaded verb. It is appropriately compact, though the brevity reflects under-specification rather than rich, well-edited content.

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 three required parameters, no schema descriptions, no enums, and no usage context, the description is not complete enough for an agent to reliably invoke the tool. The output schema covers return values, but the input side lacks acceptable account_type values and balance format. Significant gaps remain.

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

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

Schema description coverage is 0%, so the description must compensate, but it only repeats the parameter names (account_name, account_type, balance). The qualifier 'Monarch account_type' hints at a controlled vocabulary but does not enumerate valid values, and balance semantics are not explained. This is insufficient for correct parameter construction.

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 resource ('manual account'), and lists the three required inputs. It is distinguishable from sibling tools like create_transaction and get_accounts by resource type, though it doesn't explicitly contrast them. The core purpose is unambiguous.

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

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

There is no guidance on when to use this tool versus alternatives. It does not mention that this is for manual (unlinked) accounts, nor does it contrast with refresh_accounts or get_accounts. No conditions, exclusions, or alternatives are given.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description adds genuinely useful behavioral context: the update_balance flag's side effect on account balance, the sign convention for amount, and the return of created transaction details. It doesn't mention failure modes or auth requirements, but with annotation coverage present, the additional behavioral disclosure is above average.

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 docstring-style Args layout is well organized and front-loaded with the purpose sentence. Each parameter entry earns its place given the 0% schema coverage, and the update_balance explanation is appropriately detailed. Slightly verbose but justified by the need to document seven parameters.

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 7-parameter mutation tool with an output schema present, the description covers every parameter with actionable semantics, discloses the balance side-effect, and states the return value. It omits edge cases like error behavior on invalid category_id or whether the operation can be undone (relevant given update_balance=true), but these are minor given the output schema and annotations.

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

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

Schema description coverage is 0%, so the description bears full responsibility — and it delivers. All 7 parameters receive meaning beyond the raw schema: amount's sign convention (positive income/negative expense), account_id's source, date's format, category_id's requiredness and source, notes' optionality, and update_balance's behavioral semantics. This fully compensates for the schema gap.

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

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

The description opens with 'Create a manual transaction' — a specific verb and resource with the 'manual' qualifier clarifying it is for user-entered transactions rather than imported ones. It does not explicitly name sibling tools like update_transaction, but the create/update distinction is self-evident from the name and it clearly distinguishes the action.

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 implicit usage guidance by telling the agent to source account_id from get_accounts and category_id from get_transaction_categories, which are effective prerequisites. However, it never explicitly states when to choose this tool over alternatives (e.g., refresh_accounts for automated syncing, or update_transaction for modifying an existing record), leaving that 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 mark the tool as read-only, and the description adds substantial behavioral detail: filtering precedes local paging, snapshot order is preserved, next_offset drives pagination, total_count counts matching snapshots, and the upstream response is always full while the MCP response is bounded. This is rich context beyond the annotations.

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

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

The description is dense but well-structured and front-loaded with the core purpose. Every sentence adds semantic value around filtering, paging, or response bounds, with no filler or repeated schema 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?

The tool has an output schema, read-only annotations, and a description that covers parameters, pagination behavior, and response-bound implications. This is sufficient for an agent to invoke it correctly and interpret results, given the 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 0%, so the description must compensate, and it does. It defines YYYY-MM-DD bounds as inclusive and optional, limit range and default, offset as zero-based after filtering, and ties account_id to get_accounts.

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 a page of balance history for account_id from get_accounts.' This clearly distinguishes the tool from transaction-focused siblings like get_transactions and search_transactions.

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

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

It provides clear operational context: date bounds, filtering before paging, pagination semantics, and a pointer that account_id comes from get_accounts. However, it does not explicitly state when to prefer this over alternatives or list 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 annotations already declare readOnlyHint=true, indicating a read-only operation, and the description aligns with this. Beyond that, the description adds little behavioral context (e.g., error handling, pagination, or response format). It provides a minor clue about the account_id source but does not enhance transparency significantly beyond the annotations.

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

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

The description is a single, clear sentence that front-loads the tool's purpose and includes the essential source hint. There is no redundant wording or unnecessary 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?

Given the tool's simplicity (one required parameter) and the presence of an output schema, the description covers the core purpose and parameter source. It does not explicitly differentiate from get_all_holdings, but for a straightforward read operation, the description is reasonably complete. The main gap is the lack of explicit usage guidance versus siblings.

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

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

With 0% schema description coverage, the description carries the burden of explaining the account_id parameter. It adds meaning by specifying that the account_id comes from get_accounts, which helps the agent understand how to obtain a valid value. This is a useful semantic hint beyond the bare schema definition.

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 action: 'Get investment holdings' for a given account_id, and it mentions the source of account_id ('from get_accounts'). This makes the tool's purpose clear and distinguishable from broader alternatives like get_all_holdings, though it does not explicitly name sibling 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 implies that account_id should come from get_accounts, providing a prerequisite. However, it does not explicitly state when to use this tool instead of other holdings-related tools (e.g., get_all_holdings) or any exclusions. The usage context is hinted but not fully articulated.

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, so the description's 'Retrieve' aligns. No additional behavioral details (e.g., what 'linked' means) are added beyond the annotation.

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-structured sentence of 5 words, front-loading the action and resource with zero waste.

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

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

Given no parameters, clear annotations, and an existing output schema, the description is adequate for a straightforward list tool, though it could mention response scope.

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?

No parameters exist, so schema coverage is 100%. The description adds no parameter info, but none is 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 clearly states the verb 'Retrieve' and the resource 'all linked financial accounts', distinguishing it from siblings like get_account_history or get_account_holdings.

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 usage guidance is provided. The description does not specify when to use this tool versus alternatives, nor does it mention any context 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?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses that this is a multi-step operation (fetch accounts, then holdings), that these run concurrently, and that a single account failure fails the whole call. This prevents an agent from misinterpreting it as one synchronous API 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?

Three compact sentences, each earning its place: scope and exclusion, execution model, and failure semantics. The most decision-relevant information is front-loaded.

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, the description covers what the tool returns (holdings grouped by brokerage account) and the important behavioral quirks (failure propagates). Nothing needed to select or invoke it correctly is missing.

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

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

There are zero parameters and 100% schema coverage, so the schema carries no documentation burden. The description contributes no parameter meaning, but with no parameters, the baseline 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 first sentence names the exact resource (holdings), the grouping dimension (by brokerage account), and the explicit scope exclusion ('not all asset classes'). This lets an agent distinguish it from siblings like get_account_holdings and get_complete_financial_overview without opening schemas.

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

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

The description clearly frames this as the tool for brokerage-account-grouped holdings and explicitly warns it is not for all asset classes, implying a broader overview sibling should be chosen otherwise. It does not name the alternative tools explicitly, so it stops one step short of full routing 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 declare readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds genuinely valuable behavior beyond annotations: it discloses that missing end_date defaults to today and missing start_date defaults to the first day of the end's month, plus natural-language date parsing. This context is not inferable from the schema or annotations and helps the agent predict behavior on partial input.

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?

Roughly 40 words across two short paragraphs, with the core purpose front-loaded in the first sentence and the parameter behavior in the second. Every sentence earns its place — purpose, then format/defaults. Slightly more compact phrasing was possible, but it's already tight and well-structured.

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 read-only tool with two optional params and an output schema (so return format needs no description), the description is fairly complete: it covers purpose, both parameters' formats and defaults. The main gap is the lack of guidance distinguishing it from overlapping siblings like get_cashflow, get_spending_summary, and get_complete_financial_overview.

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

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

Schema description coverage is 0%, so the description must compensate for both undocumented parameters. It does so well: it explains the accepted formats (ISO strings or natural language like 'last month') and the default behavior for each parameter. This fully covers both start_date and end_date semantics, though it stops short of defining what a 'budget' range represents.

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 ('Retrieve') and resource ('budgets') with clear scoping via optional date filters. It's distinguishable from mutation siblings like set_budget_amount, but it doesn't explicitly differentiate from overlapping financial-report siblings like get_cashflow or get_spending_summary, which an agent might confuse with budget retrieval.

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 explains the date-filter behavior in detail (ISO strings, natural language, defaults for missing start/end), which implicitly guides usage — e.g., an agent can request a month's budget by supplying only a start_date. However, it gives no explicit when-to-use guidance or exclusions vs. the many similar financial tools in 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?

Beyond the readOnlyHint annotation, the description discloses meaningful behavior: it accepts ISO strings or natural language dates, and defines defaulting rules for missing start/end dates. This adds actionable context agents would otherwise not infer from the schema, though it does not describe the shape of the returned data.

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

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

The description is two sentences: the first states purpose, the second delivers essential parameter behavior. There is zero filler; every clause earns its place, and the most important information is front-loaded.

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 (two optional parameters) and an output schema exists, so the description covers the critical calling details: date formats and defaults. It could be slightly more explicit about what 'cash flow' represents semantically, but given the output schema and annotations, this is reasonably 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?

With 0% schema description coverage, the description must compensate for parameter meaning, and it does. It explains that both parameters are optional date filters, clarifies accepted formats (ISO or natural language), and specifies default behavior for missing values—adding significant value over 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 clearly states the tool's function: 'Retrieve cash flow' with optional start_date/end_date filters. It is specific about the resource and operation, but does not explicitly differentiate from sibling tools like get_spending_summary or get_transactions, so it stops short of a top score.

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 (when cash flow data is needed) but provides no explicit guidance on when to prefer it over alternatives, nor any conditions under which it should not be used. There are no mentions of sibling tools or exclusionary cases, making the guidance adequate but not strong.

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

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

Beyond the readOnlyHint annotation, the description discloses significant behavioral details: the single-page 500-entry limit, the failure behavior ('Failed API sections contain errors while successful sections remain'), the null default for raw transactions/categories unless verbose, and the transactions_truncated metadata flag. These go well beyond what annotations convey, offering the agent a clear model of the tool's output boundaries and error 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 dense but not bloated; every sentence adds value. It opens with the main purpose, then systematically covers period semantics, transaction limits, failure behavior, defaults, and the truncation flag. A minor redundancy exists between the 500-entry limit and the truncation flag explanation, but overall it remains efficient and well-structured.

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 (overview with many fields) and the presence of an output schema, the description covers all essential invocation details: parameter syntax, default/verbose returns, transaction pagination behavior, error handling, and a signal for incomplete data (transactions_truncated). An agent can call this tool correctly without needing additional information.

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

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

The input schema has zero description coverage for its parameters, so the description carries the full burden. It thoroughly explains 'period' with concrete examples ('this month', 'last month', 'this year') and the 'always today' end date, and defines 'verbose' as including full API details. This fully compensates for the schema's lack of parameter descriptions.

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

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

The description clearly states the tool 'Fetches a compact financial overview' and enumerates the specific components (account IDs/names/balances/types, monthly budget totals, cashflow totals, transaction summary). It differentiates itself from sibling tools by explicitly mentioning 'Use their dedicated tools for details', making it unmistakable that this is an aggregate overview rather than a detailed data tool.

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 explicit guidance on when to use this tool versus alternatives: it says to use dedicated tools for detailed transactions/categories, and it highlights the 500-entry page limit, implying that full history requires the dedicated transaction tool. It also clarifies the period parameter's semantics (start date or phrases, end always today) and the verbose flag's effect, giving the agent complete context for invocation.

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 already communicates that this tool is safe to call without side effects. The description adds useful behavioral detail beyond that: pending invitations are not included, and the output is designed for transaction ownership updates. It does not contradict the annotations and provides the key scoping behavior an agent would need.

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

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

The description is three short sentences, each earning its place: the first states the core action, the second defines scope exclusion, and the third explains downstream usage. It is front-loaded with the most important information and contains no filler.

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

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

For a zero-parameter read-only tool with an output schema present, the description is fully sufficient. It covers what is returned, what is excluded, and how the returned values are meant to be used. Nothing an agent needs in order to call or interpret 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?

There are zero parameters, so the base expectation is a 4. The description adds semantic value by explaining how the returned IDs should be interpreted in downstream transaction updates, including the special case of an empty string for Shared. No parameter documentation is needed beyond this.

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: 'List current household members and IDs for transaction ownership.' It also states a clear purpose (transaction ownership), which distinguishes it from all sibling tools, none of which are about household members. Even without a parameter schema, the agent knows exactly what the tool 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?

The description gives clear context for when the output is used: IDs map to owner_user_id in transaction updates, with special handling for Shared and missing/null values. It does not explicitly name alternatives, but no sibling tool provides household members, so the lack of an alternative comparison is not a meaningful gap. Exclusion of pending invitations further clarifies the expected data.

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 readOnlyHint: true, so the description adds no additional behavioral context. However, the description is consistent and 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 short, front-loaded sentence with no extraneous information. 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?

For a parameterless list tool with an output schema, the description is complete enough. It tells the agent exactly what the tool returns.

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

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

The tool has no parameters, so the description does not need to detail them. The schema coverage is 100%, meeting the baseline without additional 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 'Get linked financial institutions' uses a specific verb ('Get') and resource ('linked financial institutions'), clearly distinguishing it from sibling tools that focus on accounts, transactions, or budgets.

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 explicit guidance on when to use this tool versus alternatives. While the purpose is clear, the description lacks context about prerequisites or typical use cases.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description adds valuable behavioral context: it defines the recurring.recurringTransactionItems return structure, clarifies that isPast refers to the occurrence date rather than payment status, and explains the default date-range behavior. This goes well beyond what annotations or schema alone provide.

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

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

The description is front-loaded with the core purpose, followed by concise, logically grouped date semantics and return-structure details. Every sentence carries useful information with no repetition or filler. It is appropriately sized for the tool's complexity.

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 only two optional parameters, an output schema, and read-only annotations, the description covers everything needed for correct invocation and interpretation: what is returned, how dates behave, and how isPast should be understood. It is complete without being bloated.

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 provides no descriptions and 0% coverage, but the description fully compensates. It explains that dates accept ISO or natural language, defines the default month when neither date is provided, and specifies how a missing bound is derived from the single provided date. This adds substantial 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 opens with a specific verb and resource: 'Get scheduled recurring occurrences, not the posted transaction history.' This immediately distinguishes it from transaction-history tools, and the final sentence names get_transactions(is_recurring=True) as the recorded-transaction alternative. The purpose is unambiguous and clearly differentiated from siblings.

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

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

The description explicitly tells the agent when to use this tool: when scheduled recurring occurrences are needed, not posted history. It also names the exact alternative, get_transactions(is_recurring=True), with the condition that selects it. Date-bound defaults are documented precisely, leaving no guesswork about invocation.

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

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

Beyond the readOnlyHint annotation, the description discloses key behaviors: fetching all pages (pagination), inclusive date handling with defaults for missing values, and that expenses are positive magnitudes. It also clarifies that invalid group_by values produce a single group. This is valuable context not present in 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 concise and well-structured. The primary purpose is front-loaded in the first sentence, followed by a clear Args section and behavioral note. No redundant or filler content.

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 existing output schema and annotations, the description covers essential aspects: pagination, defaults, grouping behavior, and sign convention. It is complete enough for an agent to correctly invoke the tool without additional lookup.

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

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

Schema description coverage is 0%, so the description fully compensates. It explains each parameter: start_date inclusive and format accepted, end_date same with default behavior, and group_by with allowed values and fallback behavior. This adds substantial meaning beyond the raw 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 clearly states the tool summarizes income, expenses, and net by category, account, or month. This is a specific verb (summarize) with a clear resource and grouping dimensions, distinguishing it from siblings like get_transactions (which lists transactions) and 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?

The description implies usage when aggregate summaries are needed but does not explicitly name alternatives or state when not to use this tool. It lacks explicit routing guidance such as 'use this for totals, get_transactions for line items.'

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, so the read-only nature is known. The description adds valuable behavioral details beyond that: it explains what verbose=True does ('preserves full API details, including groups and system flags') and what the tool returns ('categories, count, and verbose'). This enriches the agent's understanding of the response behavior and the verbose parameter's effect.

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

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

The description is two short sentences plus a returns line. The first sentence states the purpose immediately, followed by a concise explanation of the verbose parameter and the output. No filler or redundancy. It is optimally front-loaded and every sentence earns its place.

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

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

For a tool with one optional boolean parameter and an output schema, the description is complete. It covers the tool's purpose, the parameter behavior, and summarizes the return fields ('categories, count, and verbose'). Since an output schema exists, the agent can rely on it for detailed structure. Nothing essential is missing for correct invocation.

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

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

The input schema provides only a boolean verbose parameter with no description (schema coverage 0%). The description fully compensates by explaining the parameter's effect: 'verbose=True preserves full API details, including groups and system flags.' This is exactly what an agent needs to decide whether to set it, making the parameter semantics clear and self-sufficient.

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'), a clear resource ('category IDs and names'), and the intended use case ('for lookups and transaction updates'). This distinguishes it from sibling tools like get_transactions or get_budgets, which handle different resources. The purpose is unambiguous and actionable.

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 conveys when to use the tool: when category IDs and names are needed for lookups or transaction updates. While it doesn't explicitly name alternatives or exclusions, the context 'for lookups and transaction updates' gives enough situational guidance. The sibling list shows no similar category-listing tool, so the usage context is effectively clear.

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

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

Beyond the readOnlyHint annotation, the description explains paging behavior ('Follow next_offset until null'), local paging semantics, page vs total counts, and the difference between compact and verbose results. This is substantial behavioral detail that an agent cannot infer from annotations alone.

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 dense but every sentence earns its place: purpose first, then parameter details, then paging behavior, then output formatting differences. There is no filler or repetition of schema defaults.

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

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

With an output schema present, the description need not restate return structure. It covers the key operational details an agent needs: paging loop, count semantics, local paging caveat, compact field omission rules, and verbose mode. This is complete for a read-only paginated list tool.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameters. It explains limit's range and default, offset's zero-based meaning, and verbose's effect on returned objects. All three parameters are given meaningful semantics 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 opens with a specific verb and resource: 'Read a page of automation rules in priority order, without modifying them.' This clearly distinguishes the tool from transaction, budget, and account sibling tools, and the read-only scope is explicit.

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

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

The description gives clear context for when to use the tool: whenever a page of automation rules is needed, with no mutation. It does not explicitly name alternatives or state when not to use it, but the purpose is unambiguous and no other sibling targets automation rules.

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 only mark readOnlyHint=true; the description adds substantial behavior: pagination means one page and count is page-only, compact vs verbose shapes, pending/notes only appear when relevant, sign conventions for amounts, and differences between merchant/plaidName and category/account names. 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?

Length is justified by 14 parameters and two return modes; content is organized into Args, result overview, compact field list, and verbose behavior. The opening sentence is front-loaded and nearly every sentence adds operational detail without fluff.

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

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

For a 14-parameter tool with no schema descriptions, this is comprehensive: all parameter formats, defaults, output fields, pagination, and cross-references are covered. An agent can call it correctly without external lookups; output schema existence further lowers the burden.

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

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

With 0% schema coverage, the description carries all parameter meaning and does so thoroughly: date formats and defaults, foreign-key sourcing from get_accounts/get_transaction_categories, comma-separated tag_ids, each boolean filter's default None, and verbose behavior. It fully compensates for the schema's lack of descriptions.

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

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

Description opens with 'Fetch one page of transactions' – a specific verb and resource, and the filter list makes the operation unambiguous. It doesn't explicitly contrast with sibling search_transactions, so it misses the top score for sibling differentiation.

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

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

Gives solid operational context (pagination with offset, date defaults, filter semantics) but never says when to choose this over search_transactions or other transaction views. There is no explicit when/when-not or alternative routing, so usage is only 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?

Beyond the readOnlyHint, the description usefully discloses that unsplit transactions return an empty splits list and enumerates the fields returned per leg. It does not discuss error behavior for invalid IDs, but for a simple read tool this is a strong level of 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?

Two tight, front-loaded sentences: one states the operation and input source, the other summarizes the return shape and the unsplit edge case. There is no filler or repetition of schema details.

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

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

For a single-parameter read-only tool with an output schema, the description is complete. It covers the input source, the returned fields, and the empty-list edge case, while the readOnlyHint covers the safety profile.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining transaction_id. It adds meaningful context by specifying that the ID comes from get_transactions or search_transactions, which is exactly what the bare parameter name lacks.

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

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

The description uses a specific verb ('Get split legs') and names the resource (transaction splits), while tying the transaction_id to get_transactions or search_transactions. This makes the tool's role clear against siblings like update_transaction_splits.

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 first sentence clearly implies when to use this tool: when you have a transaction_id from get_transactions or search_transactions and need its split details. It does not explicitly state when not to use it, such as for modifying splits, so it stops short of full exclusion 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 indicate this is not read-only, not idempotent, and not destructive. The description adds the key behavioral trait: the request is asynchronous ('do not wait for completion'). It also implies a side effect (institution refresh) that aligns with readOnlyHint=false. It doesn't disclose what the response contains or whether repeated calls are safe, but the async note is genuinely valuable beyond the annotations.

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

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

One sentence, front-loaded with the action and scope, and the critical async behavior is appended concisely. Every word earns its place. No fluff or repetition of the title.

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 tool with an output schema, the description is mostly complete: it says what it does and that it returns immediately. However, it doesn't mention what the response contains (e.g., a job ID or status), whether the refresh is per-institution or all institutions, or any side effects like rate limits or credential requirements. The output schema may cover return values, but the description could still add a note about how to check completion status.

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

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

The tool has zero parameters, so there is no schema burden to compensate for. The description correctly implies the operation applies to all accounts with no configuration. A baseline of 4 is appropriate for a no-parameter tool; the description doesn't need to explain parameters that don't 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 states a specific verb ('refresh') and resource ('institution refresh for all accounts'), and adds a non-obvious behavioral detail: it does not wait for completion. This distinguishes it from a synchronous refresh or a read-only listing tool like get_accounts. It loses one point because it doesn't explicitly name a sibling alternative or clarify what 'refresh' means in terms of data updates.

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 it: when you want to trigger a refresh of all accounts and don't need to wait. However, it provides no explicit guidance on when not to use it, no mention of alternatives (e.g., get_accounts for reading current data, or a per-account refresh if one exists), and no caveats about rate limits or prerequisites like institution login. The context is clear enough for a basic call, but the guidance is thin.

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 mark this as read-only, and the description adds significant behavioral detail: returning search_metadata, applied filters, the compact-field option via verbose, and the crucial caveat that result_count is page-specific, not total matches. This goes well beyond the structured 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 front-loaded with a one-sentence summary, then uses a tight Args list to document a large parameter set without fluff. Every line adds operational value, and the pagination caveat is placed exactly where relevant.

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?

Despite high complexity (15 parameters, no schema descriptions), the description covers all parameter semantics, defaults, pagination, and the shape of the response metadata. An agent has everything needed 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?

With 0% schema description coverage, the description carries full responsibility for all 15 parameters. The Args block explains each one, including defaults, date-range fallbacks, source tools for ID parameters, and the meaning of boolean filters. This fully compensates for the schema gap.

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

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

The opening sentence states a specific verb ('Search'), a resource ('transactions'), and a scope ('one page... using Monarch's text search'). This clearly identifies the tool's function and differentiates it from sibling tools like get_transactions without needing to inspect schemas.

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

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

The description clearly establishes the text-search use case and pagination behavior ('Use offset for further pages; result_count is not the total number of matches'). It does not explicitly mention alternatives or when not to use it, but the context is clear enough for an agent to select it appropriately.

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 signal that this is mutating (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description confirms the write behavior but adds little beyond that, such as whether an existing amount is overwritten or what errors might occur.

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 conveys the operation and the source for its key parameter with no filler. Every word contributes to understanding how to invoke the 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 low-complexity tool with an output schema and informative annotations, the description covers the essential contract: which category to target and what value to set. Minor gaps around amount semantics and overwrite behavior are not critical for a correct 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?

Schema description coverage is 0%, so the description must carry parameter meaning. It does mention both category_id and amount and usefully states that category_id comes from get_transaction_categories, but it does not clarify amount units/currency or any constraints beyond the schema's type.

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, 'Set', and names the resource, 'amount for a category_id', while tying the category_id to the sibling get_transaction_categories. This makes the write operation clearly distinct from read-only tools like get_budgets and from transaction-editing 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 prerequisite: the category_id must come from get_transaction_categories. It does not explicitly discuss when to prefer this over alternatives, but no sibling offers a comparable budget-amount update path, so 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?

The description discloses behaviors beyond the annotations: it states partial-update semantics, explains the effect of is_recurring and is_active, and explicitly denies money movement ('This does not create posted transactions or move money'). It also clarifies the meaning of frequency and base_date formats. This adds significant behavioral context not captured by the annotations (which only note idempotency and non-destructiveness).

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

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

The description is front-loaded with the core purpose and then details each aspect in logical order. Every sentence adds value: it covers scope, parameter sourcing, update semantics, and exclusions. Though lengthy, it is efficient for a tool with 7 parameters and no schema documentation. No redundant or filler sentences.

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

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

Given the tool's complexity (7 params, 2 required, no schema docs), the description is remarkably complete. It explains all parameter meanings, required input sourcing, partial update behavior, and non-transaction effects. The output schema exists and likely covers return values, so no omission is evident. The description fully equips an agent to call 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 input schema has zero descriptions (coverage 0%), so the description must fully document parameter semantics. It does: it explains how to obtain merchant_id, what merchant_name is for, the meaning of each optional field (frequency as Monarch's string, base_date as the anchor, amount as signed value), and the semantics of is_recurring and is_active. This is essential because the schema alone provides no guidance.

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 opens with a precise statement of the tool's function: 'Change a merchant's recurring schedule, not an individual transaction.' This clearly identifies the verb (change) and resource (recurring schedule) and differentiates it from transaction-level operations. The statement 'This affects the merchant-wide recurrence' reinforces scope and distinguishes it from siblings like update_transaction.

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

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

The description provides explicit when-to-use guidance: it targets the recurring schedule, not an individual transaction, and clarifies that it does not create posted transactions. It also gives operational instructions for obtaining required parameters (merchant_id from stream.merchant.id) and explains partial update semantics ('Omitted settings stay unchanged; provide at least one'). This is comprehensive guidance that an agent can follow without ambiguity.

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

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

The description goes far beyond the annotations (idempotentHint, readOnlyHint, etc.) by disclosing specific behaviors: empty strings clear fields, the API ignores empty merchant names, owner_user_id '' makes it Shared, and the update response does not include the owner so one must read verbose transactions to verify ownership. It also lists immutable attributes. This is rich, honest 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 well-structured with a clear opening sentence and bullet-like parameter explanations. Every sentence adds value, and the length is justified given the need to document 10 parameters. It front-loads the core behavior and then systematically covers each field without redundancy.

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

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

Given the complexity (10 parameters, 1 required), the description covers all necessary aspects: parameter semantics, special behaviors, exclusions (what cannot be changed), and pointers to relevant sibling tools. It also warns about the response not including owner, which is critical for verifying ownership. No critical information 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 0%, so the description is the sole source of parameter meaning. It explains every one of the 10 parameters in detail, including formats (date YYYY-MM-DD), sources (transaction_id from get_transactions), special values ('' clears notes/goal_id/owner_user_id), and the distinction between merchant_name and the read-only plaidName. This fully compensates for the lack of schema descriptions.

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

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

The description clearly states it updates a transaction and lists the mutable fields. It explicitly names sibling tools (update_transaction_splits, update_recurring_transaction) to distinguish itself, and even states what cannot be changed (ID, account, pending status, etc.). This gives an agent a precise understanding of the tool's 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?

The description provides clear guidance on when to use this tool: it mentions using update_transaction_splits for splits and update_recurring_transaction for recurring schedule changes. However, it does not explicitly mention update_transactions_bulk as an alternative for bulk operations, which is a minor gap given that sibling exists. The 'leaving omitted fields unchanged' instruction is a strong usage 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 only provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral detail: invalid items fail individually while valid items run, the batch is not atomic and does not roll back, unknown fields/wrong types are rejected, and empty notes/goal_id clear values while empty owner_user_id reassigns to Shared. This far exceeds the annotation baseline.

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 well-structured: a one-sentence summary, a detailed Args specification, validation/atomicity caveats, and an example. Every sentence adds necessary information for correct invocation, and the length is justified by the tool's complex payload.

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 single parameter's complexity, the description covers payload schema, field semantics, validation behavior, failure isolation, concurrency, and return shape ('per-item results and counts'). The presence of an output schema means return details do not need to be restated, so the description is 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 gives the updates parameter no description at all (0% coverage). The description fully compensates by specifying the JSON-array-as-string format, required transaction_id, all accepted fields, date format, type constraints, clearing semantics, and a concrete example.

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 opens with a specific verb and resource: 'Update transactions concurrently, returning per-item results and counts.' It clearly distinguishes this bulk operation from single-transaction siblings like update_transaction by emphasizing concurrency and per-item results.

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 bulk/concurrent nature and the bulk name imply this is for multiple transactions, and it references update_transaction for field semantics. However, it never explicitly says when to prefer this tool over update_transaction or when not to use it, leaving the usage decision mostly 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 indicate readOnlyHint=false and idempotentHint=true, but the description adds crucial behavioral details: the sum constraint (amounts must sum to parent's amount or Monarch rejects), sign conventions (negative expenses, positive income), default merchant behavior, and the return payload (transaction_id, has_split_transactions, resulting splits, summary). These go well beyond annotation hints and inform the agent of failure conditions.

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 well-organized: a one-sentence purpose, a bulleted parameter explanation, and a clear example. Every sentence contributes value, with no fluff. The example is placed strategically to solidify understanding without bloating the text.

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

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

For a complex replacement tool with constraints, the description covers all necessary aspects: input semantics, validation rules, return format, and even an example. The presence of an output schema (not shown) reduces the need to detail return values, but the description still summarizes them. Nothing critical is missing for an agent to call this correctly.

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

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

Schema description coverage is 0%, so the description must fully compensate. It explains transaction_id provenance and details every field of splits: amount (required, sign, sum constraint), category_id, merchant_name (default), and notes. A concrete example with a -100.00 parent further clarifies usage. This is exemplary parameter documentation.

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

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

The description opens with a specific verb and resource: 'Replace a transaction's entire set of splits, or remove all splits with [].' This clearly distinguishes it from sibling tools like get_transaction_splits (retrieval) and update_transaction (updating transaction fields). No ambiguity about the tool's core function.

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

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

The description states the primary use case (replace entire split set) and directs where to get the transaction_id (from get_transactions or search_transactions). It does not explicitly name alternative tools or exclusion criteria, but the phrasing 'entire set' implies that partial updates are not this tool's role. Sibling names reinforce the distinction.

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