Monexa

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

Annotations already declare it is a non-read-only, non-idempotent, non-destructive creation. The description adds genuinely useful context beyond them by stating the response contains the new category with its ID, but says nothing about duplicate names or whether the created category is immediately usable in records.

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, the operation is stated first and the return behavior second, with zero 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?

An output schema exists so return detail need not be spelled out, and annotations cover the safety profile for this mutation. Only edge-case behavior such as duplicate-name or invalid-color rejection is left 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 description coverage is 100%, with all four params documented including the INCOME/EXPENSE enum, so the schema carries the semantics. The description only restates the type distinction already in the enum documentation, adding no new syntax or format detail.

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 (Creates) and resource (category) plus the two subtype modes (income or expense) and the purpose (classifying records). The resource name distinguishes it from siblings like create_record and create_payment_method, though it never explicitly contrasts with 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?

No guidance on when to use this versus update_category or list_categories, and no prerequisites or constraints (e.g. duplicate-name handling). The phrase 'for classifying records' hints at purpose but is not a usage condition.

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=false, idempotent=false, destructive=false, and openWorld=false, so the safety profile is covered structurally. The description adds only that the new payment method and its ID are returned, which is minor given an output schema exists; it does not warn that repeated calls create duplicates despite 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 sentences, zero filler, with the action stated first and the return value second. Nothing is padded or redundant.

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 create tool with full annotation coverage, a complete output schema, and a fully described input schema, the description is nearly sufficient. The only real gap is the absence of any note about non-idempotent duplicate creation.

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?

Only one parameter exists and the schema documents it at 100% coverage, including an example value ('Credit Card'), so the baseline of 3 applies. The description adds no further meaning about the name field.

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 ('Creates') and resource ('payment method'), so the agent knows exactly what the tool does. It does not differentiate itself from the many sibling create_* tools beyond the resource noun, but the resource itself is unambiguous.

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

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

There is no guidance on when to use this versus create_category, create_record, or create_recurring_expense, nor any prerequisite or exclusion. The agent must infer usage entirely 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?

Goes beyond the annotations by disclosing the fallback chain for currency, payment method (most recent record, else first payment method) and date, plus the UTC-vs-local pitfall. The annotations only cover mutability; this default-resolution behavior is exactly the context an agent needs and would otherwise have to discover empirically.

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

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

Three dense sentences, each carrying a distinct fact (record type derivation, defaults, date pitfall). The date guidance duplicates the schema's date description, which is the only mild waste.

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

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

An output schema exists, so return values need no explanation, and the description still notes that the result lists applied defaults. Together with the defaults chain and date caveat, an agent has what it needs to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns one more by explaining that categoryId's type decides income vs expense, which the schema field only describes as 'Category ID from list_categories.' The date and currency default explanations largely restate schema text.

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 (Records) and resource (income or expense) and explains that the category's type determines which. It is distinguishable from update_record and delete_record, though it never contrasts with create_recurring_expense, which the name alone does not fully disambiguate.

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 conditional guidance for the date field ('pass the user's local date ... when you know it'), which is useful. However it never states when to use this over create_recurring_expense or update_record, so routing between siblings is left 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 the non-read-only, non-idempotent, non-destructive profile; the description goes further by disclosing the ongoing side effect (a record is generated on every due day) and the immediate-write case when startDate is today. It stops short of stating the failure mode for a past start date or how generated records relate to delete_recurring_expense.

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

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

Two sentences, front-loaded with the core behavior and followed by the key timing constraint. No filler and nothing redundant to the structured fields beyond a brief enum restatement.

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 an 8-parameter creation tool, the description covers the essential behavior, the timing constraint, and the immediate-effect edge case, while annotations carry the safety profile and an output schema handles return values. Remaining details (endDate interaction, categoryId sourcing) are fully documented in the schema.

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

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

With 100% schema coverage the baseline is 3, but the description adds real meaning beyond the schema for startDate: the past-date prohibition and the "today means the first record is added immediately" consequence, which the schema only implies with "today or later." The enumerated frequency values are restated from the enum, adding no new information.

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 ("Creates a recurring expense") plus the defining behavior that separates it from create_record: it "adds a record automatically on every due day" per a named frequency. An agent can distinguish it from the one-off record tools and from update_recurring_expense 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?

Gives concrete usage constraints: the start date cannot be in the past, and a start date of today triggers an immediate first record — both of which affect when an agent should call it. It does not explicitly name alternatives (e.g. create_record for one-off entries), so routing is implied rather than stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds the important behavioral fact that the operation fails under referential dependency — context 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?

Two tight sentences, front-loaded with the core action and immediately followed by the failure condition and remedy. No filler.

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

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

With annotations covering safety and an output schema present, the description only needs to convey the destructive constraint — which it does clearly. Nothing needed to invoke 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 100% and the schema itself documents the id parameter ("Category ID from list_categories"). The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource ("Deletes a category"), which cleanly separates it from update_category and list_categories. It does not explicitly name a sibling for contrast, so it lands at a solid but not exceptional 4.

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 precondition and remediation path: the delete is refused while any record still uses the category, so move or delete those records first. That is actionable when-to-use context, though it does not name alternative tools.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds non-obvious behavioral context beyond that: a referential-integrity precondition that will cause the call to fail. It stops short of stating irreversibility or what the failure/response looks like, but it meaningfully enriches the destructive semantics.

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

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

Two sentences, no filler, and the operation is front-loaded before the constraint. Every clause earns its place by either naming the action or the failure condition.

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

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

With an output schema present and annotations covering the destructive/idempotent profile, the description supplies exactly the missing piece an agent needs before calling: the in-use blocking rule. Nothing required to invoke this correctly is absent.

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

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

Schema description coverage is 100% and the single parameter 'id' is already documented as coming from list_payment_methods. The description adds no parameter-level detail, so the baseline of 3 applies — the schema does all the work.

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 (Deletes) plus specific resource (payment method), with the affected entity clearly named. It is trivially distinguishable from the other delete_* siblings (delete_category, delete_record, delete_recurring_expense) because the resource is stated in the first three words.

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 an explicit blocking condition and remediation path: the tool is refused while any record still references the payment method, and the agent should reassign or delete those records first. This is real when/when-not guidance, though it does not name a sibling tool (e.g., update_payment_method) as the alternative for the reassignment step.

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=true, and idempotentHint=true, so the safety profile is covered. The description adds nothing beyond them — it does not state that deletion is permanent, whether it cascades to recurring expenses or references, or any confirmation requirement. For a destructive operation it adds no 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?

A single sentence with zero filler, front-loading the verb and resource. It is efficient, though it is efficient partly because it omits useful detail.

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

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

With an output schema and rich annotations (destructive, idempotent, not open-world), the agent has enough to invoke the tool mechanically. However, for an irreversible destructive action the description omits any warning about permanence or side effects, leaving a gap that the annotations only partially cover.

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?

Only one parameter and schema coverage is 100%, with the schema itself explaining 'Record ID from list_records.' The description adds no further meaning (no format, no source guidance), so the baseline 3 applies when the schema does all the work.

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 ('Deletes') and a specific resource scope ('an income or expense record'), which distinguishes it from delete_category, delete_payment_method, and delete_recurring_expense by resource type. It does not explicitly name those siblings, but the resource is unambiguous.

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

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

No guidance on when to use this tool versus alternatives, no prerequisites, and no mention of the related update_record or list_records workflow. The only hint of usage is the schema's 'Record ID from list_records', which is not in the description.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond them by scoping the destruction: future occurrences stop, existing records survive. It does not discuss reversibility or confirmation requirements, but the key nuance is 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?

Two short sentences, front-loaded with the action and followed by the critical scope caveat. Every clause earns its place with no padding.

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

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

An output schema exists, so return values need not be described, and the description covers the one non-obvious behavior of this delete. It could be slightly more complete by noting alternatives for pausing, but nothing needed to call the tool correctly is missing.

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

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

Schema coverage is 100% and the sole parameter's description already tells the agent the id comes from list_recurring_expenses. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Deletes a recurring expense') and immediately disambiguates the scope of deletion: it stops future records but preserves past ones. That distinction separates it from sibling delete_record, which removes an actual record.

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 context is implied by the purpose, but there is no explicit when-to-use guidance and no mention of alternatives such as update_recurring_expense for pausing or editing instead of deleting. 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 readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds the useful behavioral detail that the date is UTC in YYYY-MM-DD and that it is the default used by create_record, which annotations cannot express.

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

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

A single front-loaded sentence that lists the return contents and ends with the most actionable detail (the create_record default). Every clause earns its place 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?

Output schema exists, so return values need not be explained, yet the description still summarizes what comes back and adds the UTC format and cross-tool default semantics. Nothing an agent needs to call 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?

The tool takes no parameters, so the baseline is 4 and there is nothing further to document. No parameter-related gaps exist.

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

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

States a specific verb (returns) and a specific resource (the signed-in user's profile) and enumerates the contents: name, email, display currency, app language, and today's UTC date. An agent can distinguish it at a glance from siblings like get_record or update_settings.

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 clear context for calling it by noting the returned date is the default create_record uses, which tells an agent to call this before creating records. It stops short of explicit when-not-to-use guidance or naming alternatives, 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 declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond purpose: it does not say what happens when the ID does not exist or belongs to another workspace, nor anything about the shape of the result — with annotations carrying the burden, that thinness is a real 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?

One short sentence with the resource and lookup key front-loaded and no filler. It is efficient, though the terseness borders on under-specification rather than exemplary structure.

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

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

With an output schema present, return values need no explanation, and annotations plus a fully documented single parameter cover most of the rest. Still missing is the not-found/miss behavior and whether the record must be in the caller's scope, which an agent would want before calling.

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

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

Schema description coverage is 100% and the single parameter's schema text ('Record ID from list_records') already tells the agent where IDs come from. The description's 'by ID' adds no syntax, format, or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Returns one income or expense record') plus the lookup key ('by ID'), so the agent knows exactly what it fetches. The word 'one' implicitly contrasts with the sibling list_records, though it never names it explicitly.

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

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

Usage is only implied: fetch a single record when you already have its ID, versus list_records for enumeration. There is no explicit when-to-use/when-not guidance, no mention of what to do if the ID is unknown, and no named alternative.

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 genuinely non-obvious behavior: amounts are converted to the display currency at each record's own date rate, and the default window is the UTC calendar month, which can diverge from the user's local month at the edges. It does not say whether categories with zero matching records appear in the result.

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

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

Three sentences, front-loaded with the returned aggregates, then the currency-conversion rule, then the date-default caveat. Little waste, though the parenthetical 'income minus expenses' restates the obvious and the FX sentence is dense.

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

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

Output schema exists, so return shape needn't be explained, and all four parameters are documented in the schema; the description fills the important behavioral gaps (default window, FX timing). The only unaddressed question an agent might have is how categories with no matching records are represented.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond it by specifying the default period when startDate/endDate are omitted (current UTC calendar month) and by explaining the local-vs-UTC date tradeoff with a concrete YYYY-MM-DD instruction. The search and paymentMethodIds semantics are left entirely to the schema, which documents them 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 and resource: totals income, expenses, net balance, plus per-category record counts and totals over a period. The aggregation scope is unambiguous. It never names or contrasts with the closest sibling (get_trend_report_data), so an agent must infer the boundary from the resource wording alone.

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

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

Usage is implied rather than stated: the description tells you how the period defaults and when to pass local dates, which is conditional guidance for calling it. It never says when to prefer this over get_trend_report_data or list_records, nor any exclusions or prerequisites.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely non-obvious behavior on top: mixed income/expense categories net out as income minus expenses, output is in the user's display currency, details are ordered largest first, and undescribed records collapse into one entry flagged isUngrouped. These are computation and shape traits an agent could not derive from the schema alone.

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

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

Two sentences, front-loaded with the primary output and followed by the two conditional behaviors, with no filler. It is dense but every clause carries information; slight length is justified by the aggregation rules it must convey.

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

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

With annotations, full schema coverage, and an output schema present, the description needs only to cover behavior not captured structurally, and it largely does. Minor gaps remain, such as whether all 12 months are always returned (and as zero when empty) and what a report with no matching categories yields.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning the schema lacks: it explains the netting semantics applied when `type` is omitted and exactly what includeDetails produces (per-category and per-label grouping, ordering, isUngrouped flag). Only `year` and `id` are left entirely to the schema, which is appropriate.

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

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

The description names a specific verb and resource ('Returns a trend report's totals for each month') and pins down scope (per month, one year, display currency), which is far more precise than the title. It does not explicitly contrast itself with list_trend_reports or get_spending_summary, so an agent must infer the split, keeping it just under 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 rather than stated: the agent can infer this tool is for aggregated monthly trend data, but there is no explicit 'use this when / not when' or named alternative such as get_spending_summary. The includeDetails clause gives conditional behavior, not selection guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful domain semantics about category-type determining income vs expense, but says nothing about ordering, pagination, or result size for a list operation, and the output schema already covers 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?

Two sentences, front-loaded with the operation and returned fields. The second sentence is domain context rather than tool mechanics; it is informative but slightly tangential to invoking the tool.

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

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

With rich annotations, a fully documented parameter, and an output schema, the definition supplies enough for an agent to call it correctly. Missing only minor operational details (ordering/pagination) that the output schema may partly cover.

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 single `type` filter is fully documented in the schema (100% coverage, enum INCOME/EXPENSE), so the schema carries the load. The description does not mention the filter at all, which is acceptable at this coverage level but adds no meaning beyond the structured field.

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 (Lists) and resource (the user's categories) and enumerates the returned fields (IDs, names, types, descriptions, colors), which clearly separates it from list_payment_methods, list_records, and the other list_* siblings. An agent can identify the resource and the operation 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?

Usage is only implied: the second sentence explains that records and recurring expenses belong to a category and that category type determines income/expense treatment, which hints at why an agent would call this. But there is no explicit when-to-use, when-not-to-use, or reference to an 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and closed-world scope, so the safety profile is fully covered. The description adds one useful relational fact (payment methods are referenced by records and recurring expenses) but says nothing about result size, ordering, or whether the list can be empty.

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

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

Two short sentences with no filler; the core purpose is front-loaded and the relational note follows. 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?

With an output schema present, the description need not describe return values, and with zero parameters there is no input detail to supply. The description covers purpose and the entity's role well; only explicit routing guidance against sibling list tools is missing.

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

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

The tool takes zero parameters, so there is no parameter semantics for the description to carry. The baseline for a no-parameter tool is 4, and nothing here misleads about inputs.

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 ('Lists the user's payment methods') and clarifies the return includes IDs, which an agent needs for downstream calls. It does not explicitly distinguish itself from sibling list tools (list_categories, list_records), but the resource noun is unambiguous enough to separate 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?

Usage is only implied: the note that 'every record and recurring expense has one payment method' hints this is the lookup step before creating/updating a record, but there is no explicit when-to-use statement, no prerequisites, and no named alternative. Adequate but leaves the agent to infer the workflow.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive local operation. The description adds useful behavioral context beyond that: default newest-first ordering, limit default, total matched count, embedded category/payment method names, per-record currency, and UTC date semantics.

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

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

The description is dense and front-loaded: purpose, default behavior, return shape, filtering, and date semantics follow in logical order. Every sentence adds relevant information for an 8-parameter list tool, 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?

Given an output schema, rich annotations, and eight optional parameters, the description covers the remaining agent-critical context: default ordering, pagination limit and total count, returned relationship names, currency handling, and date-filter timezone behavior.

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

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

Schema description coverage is 100%, so the schema already documents parameters well. The description still adds meaningful semantics for the date parameters by clarifying UTC calendar-day filtering and advising use of local YYYY-MM-DD dates for ranges like today or this month.

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: it lists income and expense records, with default ordering, returned category/payment method names, and per-record currency semantics. This clearly distinguishes it from sibling single-record tools like get_record and from category/payment-method list 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?

It explains how to narrow results using date range, category, payment methods, or text search, and gives explicit timezone guidance for date filters. It does not explicitly compare itself with alternatives such as get_record or get_spending_summary, 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds real value by explaining what a returned entry contains and defining nextRunDate as 'the next day a record will be added for it', but says nothing about result size, ordering, or whether inactive entries are included.

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

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

One front-loaded sentence with no preamble or filler, and the resource identity comes before the field list. The trailing field enumeration and the nextRunDate gloss make it a long run-on, but every clause carries information.

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

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

For a zero-parameter, non-destructive read tool with a full annotation set and an output schema, this is nearly complete. The enumeration of returned fields is arguably redundant with the output schema, but the nextRunDate definition and the active-flag mention remove genuine ambiguity.

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 no parameter semantics to compensate for; the schema is empty and requires no elaboration. The description instead spends its words on the response shape, which is the only thing an agent could be uncertain about here.

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 ('Lists') and resource ('the user's recurring expenses'), illustrated with recognizable examples (rent, subscriptions). It is clearly distinct from list_records and the create/update/delete_recurring_expense siblings by name, though it never explicitly contrasts itself with 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?

There is no when-to-use, when-not-to-use, or alternative-tool guidance anywhere in the description. The agent must infer from the tool name alone that this is the read path for recurring-expense configurations versus list_records or get_record.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description's added value is the domain definition of a trend report; it says nothing about pagination, ordering, or what an empty list means, so it adds only modest 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?

Two short sentences, front-loaded with the purpose and then the routing cue, with no redundant restatement of the title or annotations.

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

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

With an output schema present and four read-only annotations, the description need not explain return values or safety. For a zero-parameter list tool it supplies exactly the missing pieces: what the resource is and which sibling to call next.

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 and the baseline of 4 applies. The description correctly does not invent arguments.

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?

'Lists the user's trend reports' is a precise verb+resource, and the follow-on sentence defines what a trend report actually is (a category set tracked month by month), which distinguishes it from the data-reading sibling get_trend_report_data.

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

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

It explicitly names get_trend_report_data as the alternative and the condition that selects it ('use get_trend_report_data with a report ID to read its numbers'), which routes the agent correctly. It stops short of stating exclusions or prerequisites for this tool itself, so it is clear context rather than a full when/when-not rubric.

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=true, and readOnlyHint=false, so the safety profile is covered. The description adds value beyond that: it discloses partial-update semantics (only passed fields change) and, importantly, that switching type moves all of the category's records between income and expense — a significant side effect the annotations cannot convey.

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

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

One sentence covering the field set and partial-update behavior, followed by one sentence on the type-change side effect. Front-loaded, no filler, every clause 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 mutation tool with a full output schema, safety annotations already present, and 100% schema coverage, the description supplies the missing pieces (partial update, cross-record consequence). An agent has everything needed 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds the non-obvious semantics that omitted fields are left unchanged and ties the type field to a cross-record side effect. It goes beyond restating the schema's per-field docs.

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 (changes) and resource (category) and enumerates exactly which fields it touches (name, type, description, color). The resource name cleanly separates it from update_record, update_payment_method, and update_recurring_expense.

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

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

Usage is implied by the name and the create/list/delete siblings, and the partial-update note tells the agent it can pass a subset. However, there is no explicit when-to-use-vs-alternative guidance and no stated prerequisites 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 declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the mutating nature is covered structurally. The description adds no behavioral context — it does not say what the rename replaces, whether the old name is discarded, or that only the name (not other attributes) can be changed.

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

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

A single four-word sentence is maximally concise, but the brevity is at the cost of substance rather than achieved through tight writing. One short sentence that fails to cover usage, scope, or prerequisites reads as under-specification.

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 rich annotations, a fully described 2-parameter schema, and an output schema handling return values, the remaining burden on the description is small. Still, it omits any statement about what the operation actually alters beyond the name, leaving it only minimally adequate for a destructive update.

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

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

Schema coverage is 100% and both parameters are documented in the schema, including which sibling tool supplies the id. The description contributes nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ("Renames a payment method"), which is unambiguous and matches the title. However, it offers no differentiation from sibling update_* tools or any hint about scope of change beyond the name field.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as create_payment_method or delete_payment_method. The agent must infer the context entirely from the name and 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 this is not read-only, is idempotent, and is destructive. The description usefully adds partial-update semantics, but it does not explain what makes the operation destructive or mention permission/auth considerations.

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

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

The description is a single front-loaded sentence with no wasted text. Both clauses carry useful information: the operation target and the partial-update behavior.

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

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

Given the rich schema, annotations, and output schema, the description is mostly complete enough to invoke the tool correctly. Its main remaining gap is not stating when to prefer this over sibling update/create tools, but the structured fields already cover parameters and return values.

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

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

Schema description coverage is 100%, so all seven parameters are already documented in the schema. The description adds no per-parameter meaning beyond the general note that only passed fields change, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: it changes an existing income or expense record. It also adds the key partial-update qualifier that only supplied fields are modified, making it clearly distinct from create/delete/get/list record operations.

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

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

It implies use for modifying an existing record but gives no explicit when-to-use guidance, prerequisites, or comparison to alternatives such as create_record or update_recurring_expense. The agent must infer usage from the tool name and purpose alone.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description goes further by stating that resume continues from the next due day without backfilling missed occurrences, that clearEndDate makes it repeat indefinitely, and that already-added records are untouched. That is real behavioral context beyond the structured flags.

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

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

Four short sentences, front-loaded with the partial-update contract before per-parameter guidance. Slight repetition in the repeated "Set X to..." construction, but no filler.

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

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

With 11 parameters, full schema coverage and an output schema, the description covers the non-obvious behaviors an agent could get wrong (pause/resume, backfill, clearEndDate). Only the relationship to the delete/create siblings 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 100%, so the baseline is 3, but the description adds semantics the schema lacks: what isActive=false/true actually do over time, and that clearEndDate produces indefinite repetition rather than merely removing a field.

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

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

Opens with a specific verb+resource ("Changes a recurring expense") and immediately scopes it as a partial update ("only the fields you pass change"). It doesn't explicitly distinguish itself from create_recurring_expense or delete_recurring_expense, but the intent is unambiguous.

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

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

Gives clear operational context: pass only the fields to change, use isActive=false to pause and true to resume. It never names the sibling delete_recurring_expense as the alternative for removal or create for new ones, so the when-not case is left 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?

The annotations flag a destructive, idempotent write, and the description adds the key mitigating context: existing records keep their own currencies, so the change is not retroactive. It also explains downstream effect (summaries, statistics, trend reports). It does not cover auth/permission needs or the fact that calling with no arguments is a no-op, keeping it out of 5 territory.

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

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

Two tight sentences; the action and its targets come first, then the consequences. No filler, and the cross-tool reference is packed into the same sentence rather than a separate aside.

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

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

An output schema exists so return values need no explanation, and both parameters are covered by the schema plus the description's downstream effects. The only gap is the absence of any note on omitted-parameter behavior (both are optional) for a mutation 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 coverage is 100% with enums documented, so the baseline is 3. The description goes beyond that by explaining what the currency parameter actually controls downstream and that it becomes the default for create_record, which the schema alone does not convey.

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 plus two named resources ('display currency', 'app language') and the 'or both' scope. That is enough to separate it from the many update_* siblings (update_record, update_category, update_payment_method), which each operate on a different resource.

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 makes the tool's domain obvious but never says when to reach for it versus alternatives, nor any preconditions (e.g., must a profile exist, can both fields be omitted). Usage is inferable from the field list rather than stated.

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