finance

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

Annotations already signal that this is not read-only or idempotent, so the description is not burdened with the full safety profile. It does add the return behavior ('Confirmation with group details'), but does not disclose side effects such as the invitation being consumed or the user joining the family group.

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 action and uses a compact Args/Returns structure. Every sentence contributes necessary information without redundancy.

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

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

For a simple one-parameter action the description gives the parameter meaning and return type, but it omits practical context such as how to obtain the invitation_id and what state transition occurs upon acceptance. Given this is a mutating action with no output schema, a bit more behavioral context 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 coverage is 0%, and the description compensates by explaining that invitation_id is 'ID of the invitation to accept.' This adds semantic meaning beyond the schema's bare integer field and is sufficient for callers.

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 ('Accept') and resource ('pending family invitation'), clearly distinguishing this from related sibling tools like decline_family_invitation or revoke_family_invitation. Even without reading the schema, an agent knows exactly what action this performs.

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

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

The description implies the tool is for pending invitations, but it does not explicitly state when to choose acceptance over declining or revoking, nor does it mention prerequisites such as the invitation belonging to the current user. Usage context is implied rather than explicit.

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 give generic write/non-destructive flags; the description adds real substance by disclosing that it does NOT change the balance value and only removes a warning flag, so the name doesn't mislead. It doesn't address idempotency or failure modes, which is the remaining gap.

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

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

Front-loaded with the core action, then supporting context, then Args/Returns. The docstring-style Args/Returns blocks add slight overhead, but the Returns note is justified given no output schema exists.

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 1-param tool with no output schema, the description covers scope, behavioral effect, and the return value ('Updated account snapshot'). Minor omissions like behavior on non-Plaid accounts and idempotency keep it from a 5.

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

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

Schema coverage is 0%, so the description must carry the load — and it adds meaningful constraint by defining account_id as 'The Plaid-linked account', not just any account. It lacks format/type detail (integer ID), but compensates for the coverage gap reasonably well.

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

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

States a specific verb+resource — accepting Plaid's reported balance as correct and clearing the mismatch warning — and explicitly distinguishes itself from the sibling override_account_balance ('unlike a balance override'). An agent can tell exactly what this does and how it differs from the value-changing 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?

Clearly scopes applicability ('Plaid-linked accounts only') and contrasts with the balance-override alternative, implying when to use each. It stops short of an explicit when-not-to-use statement or error handling for non-Plaid accounts, but the routing intent is 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?

Annotations already indicate this is a non-read-only, non-destructive mutation. The description adds that it returns a confirmation with the activated theme, which is useful, but it does not disclose whether the change persists, affects only the current session, or validates the theme_id beyond the listed values.

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

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

The description is compact and well-structured with an action verb up front and clearly labeled Args and Returns sections. Every sentence contributes needed information without redundancy.

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

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

For a one-parameter tool with no output schema, the description covers the action, parameter values, and return value. It could mention whether activation affects the current user or the whole workspace, but given the simple scope, the missing detail is acceptable.

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 description for theme_id, but the description compensates by listing the valid identifiers (light, dark, emerald_banking, frost_glass, carbon). This gives the agent concrete options that the schema lacks, although it stops short of explaining the visual differences or return format.

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 'Activate a color theme', naming the exact verb and resource. It also enumerates the specific theme IDs in the Args section, making the tool's scope unambiguous and distinct from the sibling list_themes.

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 used to change the current theme, but it provides no explicit guidance on when to use it versus alternatives, nor any prerequisites like listing available themes first. Usage is self-evident but not explicitly contextualized.

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 it is a non-readonly, non-idempotent, non-destructive mutation, but the description adds real depth: only passed fields are written (partial update), values are re-validated server-side under a row lock (concurrency/validation), and it enumerates error modes (not Premium, account not found, bad value, nothing to apply). It stops short of discussing reversibility or auditing, so a 4 rather than 5.

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

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

Well-organized with front-loaded purpose followed by an Args block and return shape; the Args lines are justified because the schema carries no descriptions. Slightly list-like but no wasted 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?

For a 10-parameter mutation with no output schema, it covers the essentials: gating (Premium), partial-update semantics, validation, all parameter constraints, and both success and error return shapes. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 0%, so the description carries full burden and delivers: it documents all ten fields with bounds and formats (interest_rate 0-100 up to 3 decimals, credit_limit >= 0, institution max 200 chars, term_months 1-600, dates as YYYY-MM-DD), which is meaningfully more than the bare type/default 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?

Specific verb ('apply') + resource ('user-confirmed statement fields') + scope ('to one of the user's accounts'). The qualifier 'user-confirmed' distinguishes it from the sibling parse_statement, which only parses, so an agent can tell the two apart without opening either schema.

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

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

The phrase 'user-confirmed statement fields' implies this runs after parse_statement and after user confirmation, and 'Premium-only' is a clear gating condition. However, it never names the sibling tool to call first nor states when-not to use it (e.g., versus update_account or override_account_balance), leaving the workflow inference to the agent.

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 mutating call, and the description adds useful behavioral context with 'Returns: Count of updated transactions' and the case-insensitive nature of category_name. It does not disclose behavior for invalid category names, nonexistent transaction IDs, or whether existing categories are overwritten.

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 compact, uses a clear Args/Returns structure, and contains no filler or meaningless repetition. Every sentence contributes useful 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 tool with only two required parameters and no output schema, the description covers purpose, parameters, and return value adequately. It omits edge-case behavior such as partial failures or category existence requirements, but a caller has enough to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must explain the parameters, and it does: transaction_ids as the list to categorize and category_name as the case-insensitive category to assign. Both required parameters receive meaningful semantic explanations, though more detail about validation or constraints would be helpful.

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 action: 'Assign a category to multiple transactions at once.' This identifies the verb, resource, and batch scope. However, it does not explicitly differentiate the tool from similar siblings such as bulk_delete_transactions or recategorize_similar_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?

The phrase 'at once' implies this tool is for batch categorization, which gives some usage context. Yet the description provides no explicit guidance about when to prefer it over single-transaction update tools or alternatives like recategorize_similar_transactions.

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

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

Goes far beyond the annotations by disclosing the core behaviors: soft-delete with balance reversal and 7-day restorability for manual rows, hard-delete for Plaid rows and the drift rationale, skipped balance reversal for future-dated rows, and silent skipping/reporting of missing or foreign-user IDs. These are exactly the mutation consequences an agent needs and none contradict the destructive/non-idempotent 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?

Front-loads the core action, then uses clear Args/Returns structure. The prose is slightly long but each sentence conveys a distinct rule; little is wasted.

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

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

With no output schema, the description carries the return contract (per-id results, undoable flags, counts, 7-day undo note) and fully covers the destructive semantics, authorization edge cases, and edge-case row handling. Nothing essential to correct 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 coverage is 0% and the single array parameter carries no schema description, but the description supplies the crucial 'max 100' bound the schema omits and clarifies the parameter is a list of transaction IDs. That is real added meaning over an otherwise bare integer array.

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

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

States a specific verb and resource (delete multiple transactions) plus the operational scope ('at once'), which cleanly separates it from the single-row delete_transaction sibling. An agent can identify the tool's function 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 bulk/at-once framing implies when this tool applies, and the per-row semantics inform decisions, but it never names the alternative (delete_transaction for single rows, undo_transaction for recovery) or states when-not to use it. Usage is inferred rather than instructed.

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 useful behavioral detail beyond the sparse annotations: cancellation takes effect at period end, the tool returns a success/error envelope, and it is a no-op for certain subscription states. This meaningfully helps an agent predict outcomes.

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 compact and front-loaded with the primary action, followed by the most important behavioral caveat, return format, and no-op conditions. Every sentence adds necessary information with 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 tool with no output schema, the description is complete: it states the effect, the duration of continued access, the return shape, and the edge cases where the call does nothing. An agent has enough to invoke it correctly.

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

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

There are zero parameters, so there is nothing for the schema to cover or the description to explain. Per the baseline for zero-parameter tools, this is a 4.

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

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

The description states a specific verb and resource: cancel the user's paid subscription. It also clarifies the key timing detail (premium access continues until the end of the current billing period), which distinguishes it from an immediate cancellation and from sibling tools like reactivate_subscription.

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 tool is appropriate and explicitly lists no-op cases (Free, family-shared, trialing-without-card). It does not explicitly name alternative tools such as reactivate_subscription or open_billing_portal, which keeps it from a 5.

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

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

Annotations only cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior on top: the exact status vocabulary (ok / below_threshold / overdraft_risk with the meaning of cushion_shortfall and overdraft_shortfall), that shortfall entries carry amount and low-point date, and the important scope limit that 'Zoninga moves no money' so covering a shortfall happens at the user's bank. It also explains the edge case of unattributed_bills being measured against checking_total_balance rather than a single account.

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 question-first opening and the terse status bullets are well front-loaded and every status definition earns its place. The explicit 'Args:' / 'Returns:' block is partly redundant with the schema and the section on unattributed_bills is wordy, so it is dense but slightly longer than necessary.

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

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

There is no output schema, and the description compensates by stating the return shape (per-account coverage entries + overall_status + summary line) and by defining the individual fields an agent must interpret. Combined with the documented statuses and window parameter, an agent has everything needed to call and interpret this 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% and the single parameter is bare in the schema (integer with default 14, no description), so the description must carry the burden. It does: 'days: look-ahead window in days (default 14, max 90)' supplies both the meaning and the 90-day upper bound the schema omits.

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 gives a specific verb and resource — project per-account coverage of upcoming scheduled payments, bills, deposits and Plaid debt due dates — and even supplies the natural-language question it answers ('will I have enough when X hits?'). It is highly distinctive in what it computes, but it never explicitly contrasts itself with the many adjacent analytics siblings such as forecast_cash_flow, get_account_health or get_cash_flow, so an agent must infer the boundary.

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

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

Usage context is clear: it answers 'will I have enough when X hits?' and can show whether a new recurring withdrawal or scheduled payment would clear. That is a concrete when-to-use signal, but no when-NOT-to-use or named alternative is given, so the agent gets no explicit routing guidance against forecast_cash_flow.

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 beyond the annotations by disclosing concrete side effects: it creates real Account rows, archives sell/remove targets, and enforces the account limit. This is particularly valuable given that the annotations only provide negative hints (readOnlyHint=false, destructiveHint=false, etc.) and no safety profile.

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 compact and well-structured: a one-line summary followed by a detailed behavior sentence, an explicit precondition, and clearly separated Args/Returns sections. Every sentence earns its place with 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?

With no output schema, the description appropriately covers the return shape. It also explains the core side effects, the user-confirmation prerequisite, and the account-limit constraint. This is sufficient for an agent to decide when and how to invoke 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 needs to compensate, but the Args section only restates the parameter as 'The scenario to commit,' which is nearly tautological. It does not explain how to obtain or validate a scenario_id, nor what constitutes a valid scenario for this operation.

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 and resource ('Commit a scenario') and explains the concrete outcome: creating add-debt/add-asset items as real Account rows and archiving sell/remove targets. This distinguishes it from sibling tools like create_scenario, update_scenario, or delete_scenario 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 explicitly says to use this tool ONLY after confirming with the user that the change actually happened and the numbers are still correct. This is a clear conditional usage guideline, though it does not name alternative tools or explicitly say when not to use the tool.

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 annotations (readOnlyHint=false), the description discloses the exact side effects: creating a transaction, incrementing confirmed_count, and auto-enabling the rule after a threshold (default 2). This adds meaningful behavioral context that annotations alone do not 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 concise, with the key behavioral summary front-loaded in the first sentence, followed by clearly labeled Args and Returns sections. Every sentence earns its place without redundant 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 single-parameter mutation tool with no output schema, the description provides the required input semantics, the side effects to expect, and the return value ('Updated debt payment details'). The threshold behavior is also disclosed, so an agent has enough context to call it correctly.

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

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

The schema provides only the parameter name and type with no description, so the description must compensate. The 'Args' section explains that debt_payment_id is 'ID of the pending DebtPayment record to confirm', adding the necessary semantic meaning for correct invocation.

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

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

The description names a specific verb ('Confirm') and resource ('pending debt payment match'), and spells out the main effect: creating the corresponding debt-account transaction. This clearly distinguishes it from sibling tools like reject_debt_payment_match and list_debt_payments.

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 states it is for confirming a pending debt payment match, giving the agent a clear triggering context. It does not explicitly mention alternatives or when not to use the tool, but the 'pending' qualifier provides enough guidance relative to sibling confirm/reject 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 indicate this is a non-read-only, non-idempotent mutation. The description adds that the tool 'Returns updated goal details' and makes the mutation explicit with 'Add a contribution,' but it does not explain side effects such as whether a transaction is created or account balances change.

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?

Well-structured docstring with one straightforward purpose sentence, a compact Args list, and a clear Returns line. No filler; the operation is front-loaded and each section 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 simple three-parameter tool with no output schema, the description provides all invocation parameters and a return-value summary. It could be more specific about what 'updated goal details' contains, but the definition is sufficient for selecting and calling 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?

Although schema description coverage is 0%, the Args section defines every parameter with real meaning: goal_id identifies the goal, amount is a positive contribution amount, and note is optional. This goes well beyond the bare schema titles and types.

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

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

States a specific action ('Add a contribution') and target ('financial goal'), which clearly differentiates it from sibling goal tools like create_goal, update_goal, and delete_goal. The description is unambiguous about the resource being acted on.

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 for when to use this tool versus alternatives such as create_goal, update_goal, or link_goal_plan. The description implies contributing to an existing goal but does not state selection criteria, exclusions, or 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?

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false; the description does not contradict these and adds genuinely useful behavior: currency is hard-locked to USD and other values are rejected, bare domains in institution_login_url are normalized to https, Plaid-linked accounts get a login URL automatically, and include_in_debt_paydown explicitly does NOT affect net worth, total debt, or the balance sheet. It stops short of explaining duplicate-account behavior or what happens on partial failure, which would be relevant given idempotentHint=false.

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?

Long, but each parameter entry earns its place given 23 undocumented-in-schema fields, and the one-line purpose statement is front-loaded. The trailing 'Returns: Created account details' is near-vacuous but minor. Some entries (currency's docs-file reference) are slightly noisy but still informative.

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

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

For a 23-parameter creation tool with no output schema and only hint-level annotations, this is close to complete: it covers defaults, valid ranges, enum values, and cross-parameter applicability rules. Remaining gaps are return-shape detail (addressed minimally), duplicate/idempotency behavior, and error conditions like invalid account_type values, which matter given idempotentHint=false.

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

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

Schema description coverage is 0% and there are 23 parameters, so the description carries the full burden — and it largely does. It enumerates all 11 valid account_type values (the schema has no enum), gives examples and units for name, balance, interest_rate (0-100 annual %), term_months (360 = 30-year mortgage), dates in YYYY-MM-DD, and scopes conditional parameters (escrow fields = mortgage only, draw fields = HELOC only, low-balance fields = checking/savings/cash only). This is meaning far beyond what the bare typed schema provides.

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

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

States a specific verb and resource ('Create a new financial account'), which distinguishes it from sibling creators like create_transaction, create_goal, or create_hard_asset by resource type. It does not explicitly name those alternatives, but the resource noun plus the account_type enumeration makes the scope 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?

No guidance on when to use this versus import_accounts, create_hard_asset, or list_accounts-then-act workflows. There is also no mention of prerequisites (e.g. whether the account must be linked to a Plaid item afterward). The description moves straight into parameter documentation with no usage context at all.

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 indicate non-readOnly, non-idempotent, non-destructive, and openWorldHint. The description adds the default behavior for period and start_date, the limitation that rollover is only for monthly budgets, and the behavior of name defaulting to category name. These are useful behavioral details that go beyond the annotations, though it does not explicitly state side effects like potential creation of a category if not exists, which is why it's not a 5.

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

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

The description is well-structured with a clear Args list and Returns section. It is slightly verbose due to the detailed explanation of each parameter, but this is justified given the absence of schema descriptions. The information is front-loaded with the core purpose before details, and every line 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 description covers all six parameters, their defaults, constraints, and edge cases (rollover limited to monthly). It also explains the return value meaning. There is no output schema, but the description does a good job. It is slightly lacking in that it does not mention whether the tool checks for existing budgets or potential conflicts, but overall it is fairly 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?

Even though schema description coverage is 0%, the description explicitly defines each parameter in the Args list, including constraints (minimum amount, valid period options, date format, and the special behavior of name). This adds meaning beyond the schema, which only provides types and defaults. It compensates well for the lack of schema descriptions, though not for nested semantics.

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 'create' and the resource 'budget for an expense category', which is specific and actionable. It is distinct from siblings like create_category and create_goal, and the inclusion of 'create a budget' makes it 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 detailed parameter semantics including the purpose of the optional display name, which helps distinguish when to use this tool over creating a new category. It also implies the use case for multiple visibly-distinct budgets, effectively explaining when a user would want to use this tool instead of creating a category.

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, and the description confirms a creation side effect. It adds the 'custom category' framing and notes that it returns the created details, but it does not disclose behavior such as duplicate handling, uniqueness constraints, or whether creation can fail. This is adequate but not rich.

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 compact and well-organized with Args and Returns sections. Every sentence contributes necessary information: the action, the parameter constraints, and the return behavior. There is no filler 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 simple two-parameter create tool, the description covers the essential inputs and return value. It could be slightly more complete by specifying the shape of the created category details or error conditions, especially since no output schema exists, but it is sufficiently complete for correct invocation in most cases.

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

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

Schema description coverage is 0%, so the description must carry the parameter semantics. It does so fully: name is limited to 50 characters, category_type is restricted to 'income' or 'expense', and the default is 'expense'. This adds meaningful meaning beyond the raw schema, which only lists string types and a default.

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 and resource: 'Create a new custom category.' This clearly distinguishes it from sibling tools like update_category, delete_category, and list_categories, and from other create_* tools such as create_tag or create_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 no guidance on when to use this tool versus alternatives, such as when a custom category is appropriate versus using existing categories or creating a tag. There are no stated exclusions, prerequisites, or decision heuristics, leaving 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?

Reveals non-obvious behavior beyond the readOnlyHint=false annotation: matched transactions create pending debt payments that users confirm or reject, and matches auto-apply only after a configured threshold. This gives the agent important expectations about side effects and workflow.

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

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

Front-loaded with the core purpose, followed by a compact Args block and a Returns line. The length is justified because the deferred matching workflow is genuinely complex; no sentence is 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 mutation tool with no output schema, it covers the key mechanics needed to call correctly: source account, debt account, matching pattern, pending-payment lifecycle, and auto-apply behavior. It leaves the threshold configuration and duplicate/reactivation details somewhat implicit, but the provided guidance is sufficient for correct invocation.

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

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

Schema description coverage is 0%, but the description fully compensates by explaining all three parameters with practical examples (checking, mortgage), the substring match semantics, and the 200-character limit. Each parameter gains real meaning beyond its schema 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?

States a specific verb and resource: 'Create a rule that auto-matches withdrawals on an asset account to a debt account.' It goes beyond the title by explaining the matching behavior and differentiates this creation tool from update/delete/list rule 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?

Provides clear context for when to use the tool: when the user wants automatic matching of asset-account withdrawals to debt accounts via a description pattern. It does not explicitly name alternatives or exclusions, so it falls short of a 5.

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

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

Annotations already indicate this is a mutation (readOnlyHint=false), so the description adds value by disclosing the Premium requirement and that the user becomes owner. There is no contradiction with annotations, and these extra details go beyond the structured metadata.

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 succinct, front-loaded with the core action and requirement, and structured with clear Args/Returns sections. Every sentence serves a purpose with no 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 simple creation tool with one parameter, the description covers the essential prerequisites and ownership outcome, but the return value is vaguely described as 'Created group details' with no output schema to fill the gap. This leaves some uncertainty about what the agent can expect, so a 3 is appropriate.

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 the 'name' parameter. It provides 'name: Group name', which clarifies the purpose but adds little beyond the schema's title. Given the single simple parameter, this minimal addition is adequate, earning a 3.

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 a new family group' and specifies the effect 'user becomes owner', distinguishing it from invitation-based siblings like accept_family_invitation or decline_family_invitation. The verb-resource pair is explicit and 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 clear context for when to use the tool—creating a new family group—and notes the Premium requirement, but does not explicitly contrast with alternatives or state when not to use it. This is clear context without exclusions, fitting a 4.

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?

It discloses behavior beyond the annotations: it specifies that content is raw markdown, enforces character limits, returns a structured success/error dict, and mentions the staff-only category restriction. Since the annotations only contain false hints and offer no meaningful safety context, the description carries the burden and does so well, though it does not mention authentication requirements or post visibility.

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 is well-structured with a one-sentence purpose, a clear Args list, and a Returns section. It is information-dense without being bloated; every sentence either defines a parameter or explains expected outcomes. The layout front-loads the core action and then provides supporting 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?

Given there is no output schema, the description appropriately includes both success and error return formats. It covers validation and staff-only edge cases, which helps the agent handle failures. It does not mention how to obtain a valid category_slug, making the tool slightly less self-contained, though the error for unknown categories provides a signal.

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 fully compensates by explaining each parameter: category_slug is a 'Slug of the category to post in', title has a 3-200 char limit, and content is 'Raw markdown content' with a 10-10000 char limit. This adds concrete meaning and usage constraints that the input schema alone does not provide.

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: 'Create a new forum post.' This clearly distinguishes it from sibling tools like create_forum_reply, which creates a reply. The title 'Forum: Create forum post' reinforces the resource 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 usage by explaining what the tool does and what arguments are required, but it never explicitly states when to prefer this over create_forum_reply or how to discover valid category_slug values. The mention of 'staff-only category' errors hints at one exclusion condition, but there is no clear when-to-use or when-not-to-use 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=false, so the write nature is known. The description adds minimal behavioral context by noting in Returns that the post might be locked, which hints at a potential failure condition. However, it does not disclose other side effects like permission requirements or rate limits, so it adds limited value 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 concise and well-structured as a docstring with a clear one-line purpose, an Args section, and a Returns section. It front-loads the purpose and wastes no words. 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?

Given that there is no output schema, the description explicitly documents the return format and error cases. The two parameters are thoroughly explained. It lacks only minor context like prerequisites (e.g., the post must exist) but covers those via error messages. Overall, it is sufficiently complete for a simple creation 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%, but the description fully compensates by explaining each parameter: post_id is 'the parent post ID' and content is 'Raw markdown content (5-10000 chars)'. This adds essential meaning beyond the schema's bare type definitions, including a character constraint.

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 action 'Reply to a forum post' with a specific verb and resource. It clearly distinguishes from siblings like create_forum_post and update_forum_reply by the nature of the operation. No 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?

No guidance is given on when to use this tool versus alternatives such as update_forum_reply or delete_forum_reply. The description simply states what it does without contextual conditions or exclusions. An agent must infer usage from the name.

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, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral details: it returns 'Created goal details with progress' and notes that current_amount is ignored if linked_account is provided, which is additional 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 front-loaded with the purpose, then uses a structured Args/Returns format. Each line earns its place for the 10 parameters, though it is somewhat lengthy and repeats type information that could be inferred from the schema.

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

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

Given 10 parameters and no output schema, the description covers the return value and all parameter semantics. It lacks details on error handling or explicit sibling differentiation, but for a create operation it provides enough 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?

Schema description coverage is 0%, so the description must document all 10 parameters. It does so thoroughly: examples for name, minimum for target_amount, enum-like list for goal_type, date format for target_date, default and ignore condition for current_amount, hex format for color, and priority semantics. This fully compensates for the absent 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 states a specific verb+resource: 'Create a new financial goal.' This is clear and direct. However, it does not explicitly differentiate from sibling tools like create_goal_plan, list_goals, or update_goal, leaving minor ambiguity about when this exact tool is preferred.

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, nor any prerequisites such as required permissions or account state. The description only says what it creates, not when it is appropriate to call 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 cover the safety profile (non-readonly, non-idempotent, non-destructive, open world), so the bar is lower. The description still adds real behavioral context beyond them: the title length cap, the side effect of setting the linked goal's vng_goal_id, and the returned edit_url.

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

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

Front-loaded purpose followed by organized Args/Returns sections; the docstring formatting ('<' char cap, backtick field names) adds slight noise but each line carries information. No 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?

For a 10-parameter mutation with no output schema, the description documents the return payload (goal id, edit_url) and every parameter's semantics, plus the linkage side effect. Nothing an agent needs to 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?

Schema coverage is 0%, so the description carries the full burden and does: each of the 10 parameters is explained, including the timeframe enum values ('short','medium','long') that the schema leaves as a bare string and the date format for target_date. This is meaningful meaning beyond the structured fields.

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

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

States a specific verb+resource ('Create a goal PLAN on Visions & Goals') and immediately scopes it to the qualitative clarify-and-plan side, explicitly separating it from the money-tracking 'zoninga goal'. An agent can distinguish it from create_goal 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?

Gives a clear usage condition ('Suited to a vague aspiration that needs shaping') with two concrete examples, and names the alternative domain (the money-tracking side) that is a separate goal. It stops short of explicitly naming the sibling tool to call instead, but the when-to-use guidance is 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?

Annotations already establish that this is a mutating operation (readOnlyHint=false, idempotentHint=false). The description adds the purpose of net worth tracking and states the return value, but it does not disclose edge behaviors such as duplicate handling, what happens to linked_account_id, or whether creating the asset immediately affects net worth calculations. This is acceptable but not rich.

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 purpose, then uses a clean Args block to document all parameters, followed by a Returns line. There is no fluff or repetition of schema structure beyond what is needed. Each line earns its place in supporting tool invocation.

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

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

For a create operation with 8 parameters and no output schema, this description is largely complete: it covers the purpose, semantics for every parameter, optionality, and a minimal return summary. It lacks detail on error behavior, required-field emphasis, and the exact shape of the created asset response, but these gaps do not block correct invocation.

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

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

Schema description coverage is 0%, so the description carries full responsibility for parameter meaning. It does so thoroughly: it provides example name values, enumerates the allowed category values, specifies YYYY-MM-DD for purchase_date, marks optional parameters, and explains linked_account_id as an associated debt account such as a mortgage. This exceeds baseline compensation for schema gaps.

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

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

The description opens with a specific verb and resource: 'Create a hard asset (real estate, vehicle, valuable) for net worth tracking.' It names the exact domain and the purpose, distinguishing it from other create_* tools such as create_account or create_category. The title 'Estate: Create hard asset' further reinforces the 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 states a clear use context: creating a hard asset for net worth tracking. This implicitly tells an agent when to use the tool versus account or category creation tools. It does not explicitly name alternatives or provide a when-not-to-use statement, but the purpose clause is specific enough for correct selection.

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 is a non-read-only, non-destructive, non-idempotent write, so the safety profile is covered. The description adds a genuine behavioral constraint beyond the schema: target_amount must be > 0 and <= the goal target, which is the kind of validation detail the schema lacks.

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

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

Front-loads the one-line purpose before the Args/Returns sections, and every line carries information. The docstring scaffolding (Args/Returns headers) adds minor verbosity but no wasted 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?

For a non-idempotent mutation with no output schema, the definition covers purpose, all four parameters, the target_amount constraint, and confirms a created-milestone return. It omits side effects (e.g., whether reaching a milestone triggers the celebration notification) and error behavior, which are the remaining gaps.

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

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

Schema description coverage is 0%, so the description carries the full parameter burden and largely does so: it explains goal_id as the parent goal, gives concrete name examples, constrains target_amount, and clarifies celebration_message is optional and shown on completion. It does not specify units/currency for target_amount, which is the only meaningful gap.

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

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

States a specific verb and resource ('Create a milestone checkpoint within a goal'), which is distinctly more specific than the sibling list/create/update/delete_milestone names alone. It does not explicitly name sibling tools, so it stops short of a 5, but the scoping to a parent goal makes the purpose unambiguous.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives such as update_milestone or create_goal_plan. The requirement for an existing parent goal is only implied by the goal_id argument, not stated as a prerequisite.

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 indicate that this is not read-only, not idempotent, and not destructive in the usual sense. The description adds meaningful behavioral context: the first instance spawns on start_date, validation failures return an error object, and transfer_to_account_id is conditionally required. This goes beyond what the annotations 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 a well-organized docstring with a one-sentence summary, a compact Args list, and a Returns line. Every line earns its place; there is no filler or redundancy, and the most important scoping statement 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 9-parameter creation tool with no output schema and no parameter descriptions in the schema, the description is complete: it documents all required inputs, key defaults, conditional constraints, and the expected return shape including the error case. An agent has enough information 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?

Schema description coverage is 0%, so the description carries the full burden, and it succeeds. It explains every parameter: amount is a positive decimal in major units, frequency has an explicit enum, start_date has ISO format and spawn behavior, transaction_type has values and a default, and transfer_to_account_id is conditionally 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 opens with a specific verb and resource: 'Create a recurring transaction template.' This clearly distinguishes it from the sibling create_transaction by emphasizing the recurring-template nature, so an agent can tell them apart without inspecting 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 word 'recurring' implies this is for templated, repeating transactions rather than one-time ones, but the description never explicitly says when to use this tool versus create_transaction or update_recurring_transaction. Usage context is implied rather than stated, and no alternatives or exclusions are named.

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 are minimal (readOnlyHint=false, destructiveHint=false, etc.), so the description carries the behavioral burden. It discloses side effects (appears in morning brief, email if enabled), the delivery_note caveat (won't actually deliver if cadence off), and date clamping semantics—all beyond annotation scope and consistent with 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 somewhat long but every sentence adds functional value: it opens with the core purpose, gives an example, then details each parameter and the return contract. Structure with Args/Returns aids scanning, though it could be slightly tightened without losing 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 tool with non-trivial recurrence rules and a special delivery_note return case, the description covers everything needed for correct invocation: parameter constraints, recurrence behavior, return format, and a critical user-facing relay instruction. No output schema exists, but the return contract is fully described.

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 must fully document parameters. It explains text max length, frequency values with detailed recurrence rules (weekly on start_date's weekday, monthly day clamping, yearly month+day), start_date format, and end_date optionality—far exceeding 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 states a clear verb ('Schedule'), a specific resource ('a reminder'), and concrete behavior ('appears in their morning brief...'), with an example ask. This distinguishes it from siblings like delete_reminder and list_reminders without needing to open their 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?

It explicitly provides a canonical usage example ('remind me every other Friday to pay child support') and explains where the reminder appears, which guides when to use it. However, it does not name alternatives or state when not to use it, so it stops short of the 'explicit when-not' bar.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, yet the description adds real behavioral context: the 60-day auto-save window, temporary nature, and that committing later materializes add items as real accounts. It does not mention auth/permission requirements, but the lifecycle disclosure is 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?

Front-loaded purpose, then structured Args/Returns sections and a nested item-shape block. It is long but the length is justified by the genuinely complex nested item contract; the indentation is slightly scattered but no sentence is wasted.

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

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

With no output schema, the description responsibly indicates the return shape ({scenario, analysis} or {error}) and compensates for the 0% schema coverage with full parameter documentation. The internal structure of 'analysis' is left unspecified, which is a minor gap but not 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?

Schema description coverage is 0% and the items parameter is a formless object with additionalProperties=true, so the description carries the entire burden. It fully documents the item dict shapes (add_debt with enumerated account_type values and HELOC/ARM two-phase fields, add_asset, remove) plus name, description, strategy default (highest_rate/avalanche), and extra_monthly, adding substantial meaning absent from the schema.

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

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

States a specific verb and resource ('Create a what-if scenario and return its projected impact') and clarifies scope with concrete examples of what a scenario bundles (buy a car, take a mortgage). This clearly distinguishes it from siblings like commit_scenario, update_scenario, and list_scenarios without needing their 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?

Provides clear context for when to use it: a hypothetical/what-if bundling of changes that 'auto-saves for 60 days; committing it later turns its add items into real accounts.' This implies the create-vs-commit workflow, though it never explicitly names an alternative tool or states when NOT to use it, so it falls 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 indicate this is a write operation (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds the metric semantics (spending_limit vs spending_avoidance) and the target_amount behavior (set 0 for avoidance), which is useful. However, it doesn't disclose what happens on creation (e.g., whether it's immediately active, whether it affects gamification points, or whether duplicate challenges are allowed).

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 compact and well-structured with a clear Args list. Every line adds value, and the parameter explanations are front-loaded. It could be slightly more concise by removing the Returns line, but it's not bloated.

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 creation tool with no output schema, the description covers the parameters well but omits behavioral context like whether the challenge starts immediately, whether there are constraints on active challenges, or what the response contains beyond 'Created challenge details'. The sibling list shows related tools (list_challenges, join_challenge) but the description doesn't connect to them.

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. It explains the meaning of each parameter, including the relationship between metric and target_amount, and provides examples for name and category_name. It also clarifies that duration_days is 7 or 30, which the schema does not. This is strong compensation 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 states a clear verb ('Create') and resource ('personal spending challenge'), and the title adds the 'Gamification' context. It distinguishes itself from sibling tools like list_challenges and join_challenge by focusing on creation, though it doesn't explicitly name those 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 implies when to use it (when creating a spending challenge) but provides no explicit guidance on when not to use it or alternatives. Siblings like join_challenge and list_challenges exist, but the description doesn't mention them or explain the difference.

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, idempotentHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: it writes to Zoninga's own desk (not a third party), staff triage on the web hub, the user is notified of replies, priority is deliberately not settable, and it gives the return shape.

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

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

Purpose is front-loaded in one sentence, then Args/Returns are cleanly structured with no filler. Slightly longer than strictly necessary (docs URL, triage rationale) but every line adds usable 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 3-param mutation tool with no output schema, the description fully documents inputs, defaults, return shape (success/error), and downstream behavior. Nothing an agent needs to 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?

Schema description coverage is 0%, so the description carries the full burden and does: it gives length bounds for subject (1-200) and body (1-5000), enumerates the allowed category values, states the default (other) with rationale, and clarifies that priority is intentionally absent.

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

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

States a specific verb and resource ("File a new support ticket on the user's behalf") and the word "new" plus "on the user's behalf" cleanly separates it from reply_to_support_ticket, get_support_ticket and list_support_tickets. An agent can identify the action 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 implies the context (creating a fresh ticket for the user) but never states when to use this versus reply_to_support_ticket or when not to file one. The only routing signal is the note that priority is not settable here, which is helpful but not a when-to-use rule.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is covered structurally. The description adds one genuinely useful behavioral fact: names are unique per user. It does not say what happens on a duplicate name (error vs. upsert), which matters given idempotentHint=false.

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 lines, purpose first, then arguments with constraints. No filler, no restatement of the tool name beyond the imperative verb.

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-parameter creation tool with no output schema and no nesting, the argument guidance is adequate, but the description never says what is returned (e.g. the new tag's id) or how name conflicts surface. With no output schema, that gap falls 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?

Schema description coverage is 0%, so the description carries the full burden and largely does: it documents the 30-char cap and per-user uniqueness for 'name' and the hex format (``#007bff``) for 'color'. Only the color default is left to the schema's default field, and validation behavior for malformed hex is unstated.

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

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

States a specific verb+resource ('Create a tag'), which distinguishes it from update_tag, delete_tag and list_tags in the sibling set. It does not, however, say what a tag is for or how it differs from the similarly-shaped create_category or create_milestone.

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 statement of when to create a tag versus when to reuse an existing one, no mention of list_tags for discovery or update_tag for modification, and no prerequisites or exclusions. The agent must infer all routing on its own.

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 sparse annotations by explaining the date default, the 30-day future-date guard, the requires_confirmation error, and the inverted category semantics on debt accounts. It also clearly states defaults for transaction_date, category_name, and confirm_future. This gives the agent accurate behavioral expectations before invoking the tool.

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

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

The description is somewhat long, but the length is justified by the complexity of transaction_type semantics and the confirmation behavior. It is well-structured as Args and Returns, with the core action front-loaded. A few explanatory sentences could be tightened, but nothing is 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 complex creation tool with no output schema, the description covers required arguments, optional arguments, defaults, transfer requirements, and a key error case. The only gap is that the return value is only described as 'Created transaction details' without specifying which fields the agent can expect, which matters more because no 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%, so the description must carry all parameter meaning, and it does. Every parameter is explained, with especially valuable semantic detail for transaction_type, including concrete deposit/withdrawal examples for asset and debt accounts. confirm_future's purpose and failure mode are also clearly tied to the parameter.

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 clear, specific action: 'Create a new transaction.' It names the resource and is easily distinguished from siblings like create_recurring_transaction or import_transactions. The detailed type guidance further clarifies what kind of transaction entity this creates.

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 strong in-tool usage guidance, such as how transaction_type behaves differently on asset versus debt accounts and that transfer_to_account_id is required for transfers. However, it never explicitly tells the agent when to choose this tool over related siblings like create_recurring_transaction or update_transaction. There is no alternative or 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 and not destructive. The description adds the constraint that the invitation must be pending and notes that the return value is a confirmation, which is useful but limited. It doesn't disclose side effects, permission requirements, or irreversibility, though the annotation set lowers the burden somewhat.

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 compact and well-organized, front-loading the action in the first sentence and then providing structured Args and Returns sections. Every line earns its place with 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?

For a simple one-parameter mutation tool with no output schema, the description covers the core action, the parameter, and the return type. It is sufficient for an agent to invoke the tool correctly, though adding a note about recipient versus sender roles would improve it further.

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 provides only an integer parameter name with no description, and schema description coverage is 0%. The description compensates by explicitly stating that invitation_id is 'ID of the invitation to decline,' giving the parameter clear semantic 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 action ('Decline') and the resource ('a pending family invitation'), which is specific enough to understand the tool's core purpose. It doesn't explicitly differentiate from sibling tools like accept_family_invitation or revoke_family_invitation, but the verb itself makes the basic distinction obvious.

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 use this tool versus alternatives such as accept_family_invitation, send_family_invitation, or revoke_family_invitation. The description only restates the action without offering decision criteria 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?

Annotations already mark destructiveHint=true, but the description adds meaningful context: the deletion is a soft-delete and the account is merely deactivated, not permanently removed. It also discloses that a confirmation is returned. No contradiction with annotations 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 compact and well-structured with Description, Args, and Returns sections. Every sentence adds information, and the soft-delete clarification is front-loaded. No redundant or filler 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 single-parameter tool with destructive annotations and no output schema, the description covers the essential behavior: soft-delete, deactivation, and confirmation. The return specification is somewhat vague ('Confirmation of deletion'), but given the low complexity and annotations, the definition 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?

The schema provides only the name and type for account_id (integer), and schema description coverage is 0%. The description's Args section states 'account_id: The account ID to delete,' which adds minimal semantic context but largely restates what the parameter name already implies. For a single simple ID, this is acceptable but not rich.

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: 'Delete (soft-delete) a financial account.' It clearly distinguishes the action from permanent deletion by explaining the account is deactivated, not permanently removed. The title 'Accounts: Delete account' reinforces the resource 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 usage through the tool name and the phrase 'Delete a financial account,' and it clarifies the soft-delete semantics. However, it does not explicitly name alternatives (e.g., update_account) or state when not to use this tool, so selection guidance is only implicit.

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

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

Annotations already declare destructiveHint=true, but the description adds real substance: it stresses irreversibility, states exactly what is destroyed (the session plus every message), and explains how it relates to the automated retention sweep. For a destructive tool this is the right level of 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?

Front-loads purpose and the irreversibility warning in the first two paragraphs, then uses compact Args/Returns sections. The Google-style docstring scaffolding is slightly heavier than needed for a one-parameter tool, but no sentence is filler.

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

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

With no output schema, the description supplies the return contract ({'success': True, 'deleted_session_id': ..., 'deleted_messages': N} or {'error': ...}), covers the destructive semantics, and gives the motivating use case. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema description coverage is 0% for the single parameter, so the description carries the burden, but its 'Args' entry ('The chat session's ID') merely restates the schema title 'Session Id' and adds no format, type, or sourcing detail (e.g. obtainable from list_agent_chat_sessions). Minimum viable rather than genuinely informative.

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

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

States a specific verb and resource ('Delete one of the user's AI assistant chat sessions') and immediately scopes it ('including every message in it'). This distinguishes it from the many other delete_* siblings such as delete_family_chat_message without requiring schema inspection.

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

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

Gives explicit when-to-use context: for users who want to clear a session immediately, e.g. after sharing context they no longer want stored, versus waiting for the 90-day retention sweep. It does not name sibling tools like get_agent_chat_session or list_agent_chat_sessions as sources for the ID, so it stops short of full alternative routing.

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

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

Annotations already mark the operation as destructive, but the description adds the important nuance of a 'soft delete,' which is genuinely informative beyond the annotation. It also states that a confirmation of deletion is returned, giving a bit of 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 main purpose is front-loaded in the first sentence, and the rest is a compact Args/Returns structure. It is slightly redundant because the Args section repeats the schema, but it remains short and readable.

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 soft-delete operation with a destructive annotation, the description is minimally adequate: it names the resource, the parameter, and the return type. However, it leaves the meaning of 'soft delete' vague and gives only a generic confirmation as the return value, with no output schema to fill that gap.

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 only parameter description, 'budget_id: The ID of the budget to delete,' essentially restates the schema property title 'Budget Id.' It adds no guidance on how to obtain the ID, its format, or any validation rules, so it does little to compensate for the schema description coverage of 0%.

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 and resource: 'Delete a budget (soft delete).' This is clear and distinct from nearby siblings like update_budget or list_budgets, though it does not explicitly name or contrast any sibling.

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 alternatives such as update_budget, deactivating a budget, or other delete operations. No context, prerequisites, or exclusions are provided.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds value beyond annotations by noting the system-category restriction and stating that a confirmation of deletion is returned. These are relevant behavioral details not present in 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 compact and front-loaded with the action, and the system-category restriction is clearly stated early. The Args and Returns sections are mostly redundant with the schema, but the overall size is appropriately brief and readable.

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 one-parameter destructive action, the description covers the core operation, the key restriction, and the return behavior. It does not mention failure modes, cascading effects on transactions, or error handling, leaving some uncertainty for an agent invoking deletion.

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 the undocumented parameter, but it only restates 'category_id' as 'The category ID to delete' without adding real semantics. It does not explain how to obtain a valid user-created category ID, constraints, or why the ID might be invalid.

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 user-created category') and resource, and it explicitly scopes what can be deleted, distinguishing it from system categories. It also stands apart from siblings like create_category/update_category/list_categories. This is a clearly differentiated 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 useful usage context by specifying that system categories cannot be deleted, which implicitly tells the agent when not to call this tool. It does not name an alternative tool for renaming or hiding categories, but it provides a meaningful exclusion that helps route the call.

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

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

Annotations already declare destructiveHint=true and readOnly=false. The description adds meaningful context beyond this: the delete is soft, and existing DebtPayment records are retained for audit. This helps the agent communicate consequences accurately, though reversibility is not addressed.

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: purpose first, then the key behavioral consequence, followed by parameter and return details. Every sentence adds relevant information without 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 single-parameter soft-delete tool, the description adequately covers the action, the retention behavior, and the return semantics. Additional details such as permission requirements or behavior on an already-deactivated rule would be nice but are not critical.

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%, and the schema only provides the parameter name 'rule_id'. The description compensates by explicitly defining it as 'ID of the rule to deactivate', giving the parameter its operational meaning.

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

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

The description names a specific action ('Deactivate') and resource ('debt payment rule'), and clarifies the semantic as a soft delete. It also distinguishes itself from a hard delete by noting audit records are retained.

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 usage is implied: if you want to deactivate a rule, use this tool. However, there is no explicit guidance about when to prefer it over update_debt_payment_rule, or whether deactivated rules can be reactivated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation semantics are covered structurally. The description adds value beyond that with the permission model governing whose messages may be deleted, plus a note that the call returns confirmation or an error dict. It does not discuss irreversibility or side effects on chat history, keeping it below a 5.

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

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

Two short sentences plus Args/Returns blocks; the purpose and permission rules are front-loaded where an agent will read them. The explicit 'Args:'/'Returns:' scaffolding is slightly heavier than needed for a single-parameter tool but wastes little space.

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

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

There is no output schema, and the description compensates by stating the return shape ('Confirmation on success, or error dict'). Combined with the permission rules and annotations that already mark the operation destructive, an agent has everything needed to invoke 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?

With only one parameter, an integer message_id, and 0% schema description coverage, the schema itself explains nothing. The description's 'Args: message_id: ID of the message to delete' is effectively a restatement of the parameter name and adds no format, sourcing, or validation detail beyond what the schema already implies.

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 gives a specific verb and resource ('Delete a family chat message'), which is unambiguous against siblings such as edit_family_chat_message, send_family_chat_message, and list_family_chat_messages. It stops short of explicitly naming those alternatives, so it earns a clear 4 rather than a 5.

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

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

The description supplies the operative precondition for use: 'Users can delete their own messages at any time; group owners and admins can delete anyone's messages.' This tells the agent when the call is authorized, which is genuine routing-relevant context, though it never contrasts this tool with the related edit/send/list chat 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 mark this as destructive, and the description adds meaningful behavioral detail beyond that: replies cascade, authorization is limited to author/staff, and errors are returned for not-found or unauthorized cases. The exact success and error return shapes are also 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?

The description is compact and front-loaded, with the core behavior stated first, followed by minimal Args and Returns sections. Every sentence adds value and there is no redundant or promotional language.

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 parameter, and the description covers the key requirements: what is deleted, who may delete, what happens to replies, and what response to expect on both success and failure. No output schema exists, but the return contract is explicitly documented.

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 must clarify the parameter, and it does: 'post_id: The post to delete.' It also reinforces that the returned deleted_post_id is the same identifier, which is useful given 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 action ('Delete a forum post') on a specific resource, and clarifies authorization ('author or staff'). It also distinguishes posts from replies by noting that replies cascade, which separates it from delete_forum_reply.

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: it is for posts, not replies, and only the author or staff can perform the deletion. It does not explicitly name alternatives like delete_forum_reply, but the resource scope and authorization condition are enough to guide correct usage.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds meaningful behavioral detail: the authorization requirement, the exact success return shape, and the error conditions (not found, or not author/staff). This goes beyond the structured annotations without contradicting 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 compact and front-loaded, with the core action stated first. The Args/Returns formatting organizes the information efficiently with 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?

For a one-parameter destructive action with no output schema, the description covers all essential aspects: target identification, authorization, success return value, and error cases. Nothing an agent needs to 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?

Schema coverage is 0%, so the description must carry parameter meaning. 'reply_id: The reply to delete' clarifies that the integer identifies the target reply and is required. It is minimal but adequate for the single simple parameter.

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: 'Delete a forum reply.' It also states the permission context (author or staff), which distinguishes it from related tools like update_forum_reply or delete_forum_post. The purpose is immediately 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 clear context for when to use the tool by noting that only the author or staff can delete. It does not explicitly name alternatives or exclusions, but the forum-reply scope and permission condition make selection straightforward among 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 declare destructiveHint=true and readOnly=false, and the description adds the meaningful nuance that this is a soft delete, not a permanent hard deletion. It also specifies that a confirmation is returned. This adds context beyond the structured annotations, though it stops short of describing reversibility or impact on related 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 tightly structured into purpose, argument, and return sections. There is no filler or redundant explanation, and the core action is front-loaded. 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 one-parameter soft-delete tool, the description gives the essential information: what it does, the parameter meaning, and the confirmation return. It lacks notes on post-cancellation visibility, reversibility, or effects on linked resources, but it is still nearly complete for invoking 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 schema has one required integer parameter with no description (0% coverage). The description compensates with an Args section stating that goal_id is 'The ID of the goal to cancel.' For a single, simple parameter this is sufficient, though it does not indicate where to obtain valid goal IDs.

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 ('Cancel') and resource ('a financial goal'), and clarifies the mechanism ('soft delete'). This is easily distinguishable from the many sibling delete_* tools because it names the exact target resource and the action type.

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, nor any exclusions. It does not mention related tools like update_goal, list_goals, or link_goal_plan, nor what happens to linked plans or shared goals when a goal is cancelled. Usage is implied only by the verb 'Cancel'.

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 destructiveHint=true, so the description wisely adds the key nuance 'soft-deactivate,' indicating the deletion is not necessarily a permanent hard erase. It also discloses the return contract ('Confirmation message'), adding value beyond the annotations without contradicting 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 compact and well-structured: a one-line action statement followed by Args and Returns sections. There is no filler, and each section 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 one-parameter mutation with no output schema, the description covers the action, the parameter, and the return value. However, it omits consequences such as reversibility, effects on related data, or whether the asset remains visible in any list, leaving the agent to infer what 'soft-deactivate' means operationally.

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 Args line must carry the semantic load. It correctly identifies asset_id as 'ID of the hard asset to delete,' which is sufficient for a single required integer, but it adds little beyond the schema title and gives no source, format, or prerequisite details.

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

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

States a clear verb-resource operation: 'Delete a hard asset (soft-deactivate).' The parenthetical removes ambiguity about whether this is a permanent physical delete, and it clearly distinguishes the tool from sibling update_hard_asset and create_hard_asset.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tools are named. The purpose line implies the tool is for removing or deactivating a hard asset, but the agent is left to infer edge cases and 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 reveals that milestones are hard-deleted and not user-facing records, which goes beyond the destructiveHint annotation by explaining the consequence. It also states the expected return (confirmation of deletion), adding useful behavioral context that the structured annotations do not 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 short and front-loaded, with the core action in the first sentence. The Args and Returns sections are standard and minimal, containing no filler or redundant content. Every sentence serves a purpose.

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 one-parameter delete operation with destructiveHint and idempotentHint annotations provided, the description covers the action, parameter, and return value. It does not address error cases or prerequisites, but these are not critical for a straightforward deletion 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 schema provides only the parameter name and type with no description (0% coverage), so the description's clarification that milestone_id is 'the milestone ID to delete' is essential and directly compensates. It fully explains the single parameter's meaning and role.

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 'Delete a milestone' with a specific verb and resource, and the parenthetical clarifies hard-deletion, which distinguishes it from update_milestone or create_milestone. The intent is unambiguous and well-scoped.

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

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

There is no explicit guidance on when to use this tool versus alternatives, no prerequisites, and no mention of exclusions. Usage is only implied by the name and the action 'Delete a milestone', which is insufficient for distinguishing appropriate invocation 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 destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description still adds value by stressing permanence ('removes the notification from the user's history entirely') and documenting failure semantics (error if the notification doesn't exist or isn't owned by the caller). It stops short of noting irreversibility/confirmation behavior explicitly, so not a 5.

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

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

Front-loaded with the core action, then the sibling contrast, then Args/Returns. Every sentence earns its place; the only friction is the verbose docstring-style Args/Returns block for a single-parameter 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?

With no output schema, the description usefully documents the return shape (success/deleted_id on success, error string on missing/unauthorized). For a one-parameter destructive tool, deletion semantics, alternatives, and error cases are all covered.

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

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

Schema description coverage is 0% and there is one integer parameter, so the description carries the burden. It gives only a bare restatement ('ID of the notification to delete'), adding no format, source, or constraint detail beyond the parameter name.

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

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

States a specific verb and resource ('Permanently delete a notification from the user's inbox') and immediately distinguishes the action from the sibling mark_notification_read by contrasting destructive deletion with non-destructive read-marking.

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

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

Gives a concrete use case ('dismissing an old Weekly Recap row') and an explicit alternative with its selecting condition: 'marking it read is the non-destructive way to clear an unread badge.' When-to-use and when-to-use-something-else are both covered.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: deletion is permanent and payment discussions for that context fall back to the account's bank link. It also discloses the return shape, though it doesn't cover error conditions in detail.

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 body is short, front-loaded with the core action, and the consequence follows immediately. The Args/Returns scaffolding is somewhat boilerplate given the schema already defines the argument, but overall it is efficient and readable.

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

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

With no output schema, the description supplies the return shape, and for a destructive mutation it discloses permanence and the downstream fallback behavior. Error handling is mentioned only vaguely ('an error when not found'), which is the main residual gap.

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% for the single parameter, so the description must compensate. 'payment_link_id: The link's id' largely repeats the parameter name and adds no format, source, or lookup guidance (e.g., where to obtain the id), doing little to compensate for the coverage gap.

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

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

States a specific verb and resource ('Delete ... saved payment links permanently'), which clearly separates it from save_payment_link and list_payment_links. It does not explicitly name sibling tools or contrast against them, so it falls just short of a 5.

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

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

Usage is implied by 'one of the user's saved payment links,' and the fallback sentence conveys a consequence of using it. However, there is no explicit when-to-use/when-not guidance and no named alternative (e.g., prefer save_payment_link over deleting).

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, but the description adds important scoping: only the template stops producing future instances, and existing child transactions remain untouched. This gives the agent a precise mental model of what will and will not be destroyed.

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 compact and front-loaded: the core action appears first, the critical side-effect nuance follows immediately, and the parameter documentation is minimal and direct. 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 single-parameter deletion tool with a destructive annotation, a clear description of the target, and no output schema, nothing essential is missing. The description fully covers what the tool does, what it does not do, and how to supply the required identifier.

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

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

The schema provides only an integer type with no description, so schema coverage is 0%. The description compensates by defining template_id as the template Transaction.id, clarifying that it is the recurring template's identifier rather than a child transaction ID or arbitrary ID.

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 exact operation and resource: deleting a recurring transaction template. It further distinguishes this from deleting regular transactions by explicitly targeting the template rather than spawned children, which differentiates it from sibling tools like delete_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 clear context for when this tool is appropriate: when the goal is to stop a recurring template from producing future instances. It explicitly warns that already-spawned children are not touched, signaling that this is not the tool for removing individual child transactions, though it does not name the alternative tool.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description usefully adds that the deletion is permanent and that a not-found case returns an error, but says nothing about permissions or whether dependencies (e.g. notification state) are affected.

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?

Short and front-loaded, with the core action stated first and the argument/return details following in a docstring format. Slightly rigid Args/Returns scaffolding for a one-parameter tool, but nothing is wasted.

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

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

With no output schema, the description helpfully documents the return shape ({"success": True, "deleted_id": ...}) and the failure case. For a simple single-parameter delete whose destructive nature is already in annotations, the essentials are present.

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

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

Schema description coverage is 0% and the description only says "reminder_id: The reminder's id," which essentially restates the parameter name. It does not clarify the integer type, where the id comes from (e.g. list_reminders), or how to recover from a bad id beyond noting an error is returned.

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

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

States a specific verb and resource ("Delete one of the user's scheduled reminders") plus a manner qualifier ("permanently"). It does not, however, name or distinguish itself from relevant siblings such as create_reminder or list_reminders, so the agent gets a clear action but no routing signal.

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 when-to-use, when-not-to-use, or alternative guidance. Nothing tells the agent how this differs from list_reminders or whether a soft-delete alternative exists. The description assumes the caller already knows it wants to delete.

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

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

Without the description the agent would only see destructiveHint=false and idempotentHint=false; the text explains that this is a soft-delete that hides but retains the record, which resolves the otherwise confusing non-destructive annotation, and it also discloses the return payload. It stops short of saying whether archiving is reversible or who may perform it.

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

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

Front-loaded one-line purpose followed by the soft-delete caveat, then Args/Returns; every line earns its place, though the labeled Args/Returns scaffolding is slightly heavier than needed for a single scalar parameter.

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

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

With no output schema, the inline Returns block usefully describes the success and error shapes, and the soft-delete note covers the main behavioral question for a one-parameter mutation. Missing only permission/authorization context and whether an archived scenario can be restored.

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, yet 'scenario_id: The scenario to delete' essentially restates the field name and adds no format, source (e.g. from list_scenarios), or validation detail. Minimal compensation for the coverage gap.

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

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

States a specific verb (delete) plus the resource (what-if scenario) and immediately disambiguates by glossing the operation as 'archive', which separates it from hard deletes such as delete_transaction and from sibling scenario tools (get_scenario, update_scenario, commit_scenario).

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

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

Usage is only implied by the name; there is no statement of when to archive a scenario versus committing, updating, or simply listing it, and no prerequisites. Adequate but with a clear gap.

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

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

Annotations already declare destructiveHint=true, and the description adds meaningful context by disclosing that the tag is removed from every attached transaction while transactions themselves remain untouched. This goes beyond the annotation by clarifying the scope of the destructive behavior, which is valuable for an agent assessing impact.

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 tight sentences with zero filler. The primary action is front-loaded in the first sentence, and the second sentence adds an essential behavioral caveat without redundancy. 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 simple one-parameter destructive tool with annotations covering the safety profile, the description covers the key behavioral nuance (transaction preservation) and operation scope. It lacks explicit irreversibility notes, but destructiveHint already communicates that, and no output schema exists to be explained. The only minor gap is not stating error behavior for a non-existent tag.

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 parameter explanation, but it does not explicitly describe tag_id. The parameter is a single obvious integer ID and the action 'delete a tag' strongly implies its meaning, so the gap is minor. Still, the description adds no direct parameter-level semantics.

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: 'Delete a tag.' It further distinguishes itself from sibling delete tools by naming the exact resource (tag) and specifying the effect. The second sentence clarifies the scope, making it unambiguous among many delete_* 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 the tool is used to permanently remove a tag and explains the side effect on transactions, but it does not explicitly state when-not to use it or mention alternatives such as update_tag or list_tags. Usage context is clear from the name and effect, but no explicit routing guidance is provided.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false. The description adds value beyond these by specifying that the transaction's balance effect is reversed and that the return value is a confirmation with the updated account balance. This gives the agent a clear model of the operation's side effects.

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 compact and well-structured: the action is stated first, followed by an Args section and a Returns section. Every sentence contributes necessary information without repeating the title or restating the schema.

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

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

For a single-parameter destructive operation, the description covers the action, the balance effect, and the return format. Annotations already convey destructiveness, so no further behavioral disclosure is required. The absence of an output schema is compensated by the explicit Returns statement.

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%, but the description includes an Args section defining transaction_id as 'The ID of the transaction to delete'. This provides the meaning the schema lacks, turning a bare integer into an actionable identifier. It is concise but sufficiently specific.

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

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

States a specific verb and resource: delete a transaction. The additional clause 'reverse its balance effect on the account' clarifies the scope and consequence of deletion. This clearly distinguishes it from sibling tools like bulk_delete_transactions or undo_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?

No guidance on when to use this tool versus alternatives such as bulk_delete_transactions or undo_transaction. It does not mention prerequisites, exclusions, or scenarios where another tool would be more appropriate. The usage context is left entirely 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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds valuable specifics beyond that: it sets recommendation_dismissed_until to 30 days from today and explicitly does not change the budget amount or spending 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 first sentence front-loads the core action, and the remaining sentences add behavioral detail and return format without waste. The Args/Returns structure is appropriate because there is no output schema.

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

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

For a simple one-parameter mutation with no output schema, the description covers the action, exact field changed, duration, side-effect boundaries, parameter constraint, and return shape. 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?

Schema description coverage is 0%, so the description must compensate. It does by specifying that budget_id refers to the caller's own, active budget, adding a meaningful ownership/state constraint beyond the bare integer type 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 states a specific verb (snooze/dismiss), resource (spending-recommendation nudge for a budget), and scope (30 days). It also maps to the exact field being set, making it easy to distinguish from other dismiss_* and update_budget 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 explains what the tool does but offers no guidance on when to use it versus alternatives such as dismiss_payment_warning, dismiss_celebrations, or update_budget. There are no exclusions or prerequisites stated beyond the implicit 'caller's own, active' note.

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, destructiveHint=false, idempotentHint=false, so the agent knows this is a non-read, non-destructive, non-idempotent operation. The description adds that it marks milestones as celebrated and returns the count, which is useful. It doesn't disclose side effects like whether dismissed milestones can be re-dismissed or if this affects gamification state beyond visibility, but the annotations cover the basic safety profile.

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 compact and front-loaded: a one-sentence purpose, then Args and Returns sections. Every sentence earns its place, and the format is 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?

For a simple one-parameter tool with no output schema, the description covers the main action and return value. It lacks details about error behavior, whether the operation is idempotent (annotations say it isn't), and how it relates to the gamification system's celebration lifecycle. Given the simplicity, it's adequate but not rich.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain that milestone_ids is a list of milestone IDs to dismiss, which adds meaning beyond the raw schema. However, it doesn't specify constraints like whether IDs must be valid existing milestones, whether duplicates are allowed, or what happens if an ID is invalid. The description provides the core semantic but not edge-case 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 states a specific verb ('Mark') and resource ('financial milestones as celebrated'), and clarifies the user-facing meaning ('user has seen them'). It is distinguishable from siblings like dismiss_budget_recommendation and dismiss_payment_warning by the resource type, though it doesn't explicitly name those alternatives.

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: call this when the user has seen a financial milestone and it should no longer be shown as a celebration. It does not explicitly state when not to use it or mention alternatives like get_celebrations or list_milestones, but the context is reasonably 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?

Goes well beyond the annotations by disclosing exactly what is mutated (clears next_payment_due_date and is_overdue) and that the change is transient because both repopulate on the next Plaid liabilities sync. That reversibility/regeneration detail is precisely the kind of behavioral context annotations don't supply, and nothing contradicts the 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?

Front-loads the one-line purpose, then conditions, effects, args, and returns. Every sentence earns its place, though the blank-line-separated Args/Returns scaffolding is slightly more verbose than needed for a single-parameter 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 narrow mutation tool with annotations covering safety and no output schema, the description is complete: it explains the trigger, the exact fields cleared, the regeneration behavior, the sole argument, and the return shape. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0% and the single parameter (account_id) is undocumented in the schema, but the description compensates by explaining it is the Account.id whose warning should be cleared. Good compensation; minor room for the expected id format.

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

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

States a specific verb (dismiss) plus resource (past due payment warning) and scope (on a debt account). It is clearly distinguishable from siblings like confirm_debt_payment_match, reject_debt_payment_match, and dismiss_budget_recommendation.

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

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

Gives a concrete triggering condition: dashboard shows past due but the user knows the Plaid data is wrong (e.g. paid offline, not yet picked up). This is strong when-to-use guidance, though it names no explicit alternative tool or exclusion.

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 is a non-read-only, non-idempotent, non-destructive mutation. The description adds meaningful context beyond that: an ownership/authorization constraint (only the user's own messages) and a content length limit (1-500 chars), plus a return contract. It doesn't cover reversibility or rate limits, but the added constraints are substantive given 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 front-loaded with purpose and the ownership rule, then uses clean Args/Returns sections. It is appropriately sized with little waste, though the explicit Returns section is mildly redundant given 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?

For a simple two-parameter edit tool with no output schema, the description covers the purpose, the key authorization constraint, both parameter meanings, and the return value ("Updated message on success, or error dict"). Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It compensates partially for content by adding a 1-500 character constraint not present in the schema, but message_id is only restated ("ID of the message to edit") with no format or source guidance. This is minimum viable rather than rich 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 uses a specific verb and resource ("Edit one of the user's own family chat messages") and immediately distinguishes the operation from siblings like delete_family_chat_message and send_family_chat_message by stating ownership scope. An agent can tell exactly what this tool 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?

It gives a clear usage condition and exclusion ("Other members' messages can't be edited"), which directly tells the agent when this tool is and isn't applicable. However, it does not name explicit alternatives (e.g., send_family_chat_message for new content), so it stops 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: it exports only active accounts, enumerates the exact columns produced, and notes it mirrors the web download and REST data/export_accounts endpoint.

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

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

Front-loaded with the core action, then the column list and return contract. The column enumeration is slightly long but earns its place by telling the agent exactly what the CSV contains; no filler prose.

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

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

No output schema exists, but the description supplies the return shape ({csv_data, row_count}) and clarifies the header row, so an agent knows what it will get back. Complete for a zero-parameter export 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 takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The column list is output semantics rather than input semantics, but it is still useful.

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

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

Specific verb (export) + resource (active accounts) + format (CSV text), and it explicitly distinguishes itself from the transactions CSV export sibling. An agent can tell this apart from export_transactions_csv and export_all_data without opening a schema.

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

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

States the scope ('active accounts only') and points to the transactions CSV export as the separate path for transactions, which routes the agent away from a plausible mistake. It stops short of naming export_all_data as the alternative for a full dump, so it is clear context without full exclusion coverage.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds behavior beyond them: the Premium-only gate, the error shape returned when the user is not Premium, and the fact that zip_base64 decodes to a real .zip while the CSV strings are directly readable. That is real, non-redundant context for a zero-parameter export.

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

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

Front-loaded with the core action and scope in the first sentence, followed by the Premium/parity caveat and a structured Returns block. Slightly verbose with backtick formatting and the REST-parity sentence, but every sentence carries useful information.

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

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

No output schema exists, so the description carries the return contract itself and does so fully: success payload fields, the filename pattern, counts, and the error case. An agent has everything needed to call and interpret the result.

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

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

The tool takes no parameters, so the baseline is 4; there is nothing for the schema to document and nothing the description needs to compensate for. No parameter-related guidance is missing.

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

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

States a specific verb and resource with explicit scope: the user's full data set (all accounts + all transactions) delivered as CSV strings plus a base64 ZIP. It also names the exact sibling alternatives (export_accounts_csv / export_transactions_csv) and explains how this tool differs from them.

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

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

Explicitly tells the agent when to pick this over the free per-resource exports ('The per-resource account and transaction CSV exports are free; this Premium "export everything" call bundles both in one response') and discloses the Premium precondition. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the useful behavior that the tool returns 'CSV data as a string with column headers', which is a non-obvious output trait. It does not discuss edge cases like date inclusivity or row limits, but the annotation coverage lowers the burden.

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 compact and well organized with clear sections: one-sentence purpose, parameter list, and return statement. No redundant or filler content is present, and each line 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, optional-parameter export tool, the description provides sufficient information: the action, the filters, and the return type. It does not list exact CSV headers or when to prefer sibling export tools, but these are minor gaps given the simple surface area and helpful 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 carries full responsibility for explaining parameters. It provides a one-line meaning for each parameter and specifies the date format (YYYY-MM-DD). It could clarify default behavior when no filters are given, but it already adds meaningful semantics beyond the bare schema properties.

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

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

States a specific verb ('Export'), resource ('transactions'), and output form ('CSV data'), which clearly differentiates it from siblings like export_accounts_csv and export_all_data. The title reinforces the same scope. An agent can identify what this tool 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 optional filter parameters imply usage for exporting transactions by account and date range, but the description does not explicitly say when to choose this over list_transactions, export_accounts_csv, or export_all_data. There are no stated exclusions or alternative-routing guidance, so usage 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?

Annotations already declare readOnly, idempotent, non-destructive behavior, so the burden is lower. The description goes beyond them by disclosing the double-counting rule for already-fired templates, the scheduled_income_added/expenses_added breakout, and the clamped_months_ahead / validation-error edge cases — genuinely useful behavior beyond structured fields.

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

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

Front-loaded with the core purpose, then structured Args/Returns sections. It is verbose — the Phase 115 reference and extended prose on the bias mechanism are heavier than strictly necessary — but each part informs correct invocation of an analytical 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?

With no output schema, the description usefully documents the return shape (balance, averages, projections, scheduled_templates_count, note) and covers both parameters. It is nearly complete for this analytical tool; only corner cases like empty history/no accounts are unaddressed.

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 carries full load. months_ahead is richly specified (default 3, max 12, <=0 error, >12 clamped with a response flag), which compensates well; account_id is thinner ('optional - project for a specific account only') but adequate given the integer type is 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?

States a specific verb and resource ('Project cash flow for the next N months') and immediately scopes it as forward-looking, which implicitly separates it from the historical sibling get_cash_flow. An agent can tell what this 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 explains the forecasting methodology in detail, which implies when the tool is relevant, but it never explicitly states when to pick this over alternatives like get_cash_flow or get_period_summary, nor any exclusions. Usage is left to inference from the purpose.

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