CDF Finance

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

Beyond the readOnlyHint and destructiveHint annotations, the description reveals important behavioral details: count/total sum all open installments without date filtering, including overdue ones; upcoming returns at most 5 installments sorted ascending and prioritizes overdue unpaid installments first. This meaningfully informs the agent about edge-case behavior without contradicting any annotation.

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

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

The description is dense but every sentence earns its place: it defines the resource, clarifies scoping behavior, explains the upcoming field's ordering, and routes to alternatives. It is front-loaded with the core definition and contains no filler or repetition.

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

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

Given the tool has no parameters and an output schema exists, the description covers all the behavioral context an agent needs: scope, exclusion of card invoices, aggregation semantics, ordering behavior, and alternative tools. Nothing critical is missing for correct selection and invocation.

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

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

The tool has zero parameters, and schema coverage is 100% (vacuously). Per the baseline rule, a no-parameter tool receives a 4 since there is no parameter semantics to enhance; the description instead usefully explains response field semantics such as count, total, and upcoming.

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

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

The description clearly identifies the resource: unpaid installments of installment purchases, explicitly excluding credit card invoices and defining them as any payment method with totalInstallments > 1. It also names the two closest sibling tools (invoice_for_period and list_pending_invoices) and states what this tool is not, making differentiation 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?

Usage guidance is explicit: use this tool to understand the user's overall installment purchase commitment. It also provides direct when-not-to-use guidance by pointing to invoice_for_period for a specific card's monthly invoice and list_pending_invoices for pending card invoices generally.

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, idempotentHint=false), the description discloses key behavioral traits: it always inserts a new row and never overwrites or deduplicates, consistent with the non-idempotent flag, and it reveals the important side effect that the investment's own value/cost is updated to this valuation, becoming the 'current' value returned by list_equities. It also clarifies what it does NOT touch (name, ticker), which is valuable context for a mutation 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?

Four sentences, each carrying necessary information: core purpose, insert-always semantics, date default behavior, side effect, and sibling differentiation. The most important behavioral facts are front-loaded and 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?

For a mutation tool with two required parameters and a significant side effect on the parent investment, the description covers everything needed for correct invocation: non-idempotent insert behavior, date semantics, the side effect on current value, and which sibling to use instead. An output schema exists, so return values do not need to be explained.

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 schema already documents all four parameters well (id as equity id, cost defaulting to value, date defaulting to now for backfill). The description re-states the id/date clarifications and ties the value/cost side effect to the parameters, but this is behavioral context more than new parameter semantics, so the baseline of 3 applies.

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

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

The description states a specific action — 'Adiciona um ponto no histórico de valor de um investimento' (adds a point in the value history of an investment) — with a clear resource and the crucial distinction that `id` refers to the investment/equity, not the valuation. It also explicitly differentiates itself from the confusable sibling update_equity.

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 names update_equity as the alternative and gives an explicit decision rule: use this tool to register history at a specific date without touching other investment fields, and use update_equity to edit the investment with today's date. It also tells when to use the `date` parameter for retroactive backfill.

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 readOnlyHint/destructiveHint annotations, it discloses non-obvious behavior: continuous months including those without movement, reconstructed balance, computed statistics, up to 120 months of history, and accepted date formats. No contradiction with annotations.

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

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

Description is dense but front-loaded: core purpose and scope first, then limit/date syntax, then sibling routing. The statistics list is long but informative; there is 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 read-only analytics tool with an output schema present and only two optional parameters, the description covers what it returns conceptually, how to scope dates, the range limit, and how it differs from related tools. Nothing critical 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 schema already covers the two optional date parameters at 100% with syntax and defaults. The description adds a meaningful constraint: the range can span up to 120 months (entire life), which helps an agent choose a valid 'from' value.

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

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

The description clearly identifies the tool as a continuous monthly financial history series with reconstructed balance, net worth, and statistics, and explicitly contrasts it with category_history, wealth_evolution, and financial_snapshot. This differentiates it from siblings without needing to inspect schemas.

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

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

It gives direct instructions: use for general monthly history (balance/equity/income/expense), and names sibling tools for category series, investment appreciation, and current snapshot. It also documents supported range and date formats, leaving no ambiguity about when to use this 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 establish readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable non-obvious behavior: it can return an empty list when no pattern is detected, and each result item comes with a pre-written narrative `text`. It also discloses the analytical scope, which goes beyond what the annotations or schema 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 compact and front-loaded with the core value ('already analyzed and ready to narrate'), then covers empty-list behavior and sibling differentiation. Every sentence earns its place, and the structure 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?

Given zero parameters, read-only annotations, an output schema, and a description that explains return behavior and distinguishes it from related tools, the agent has everything needed to invoke and interpret this tool correctly. The empty-list case and ready-made `text` field are explicitly addressed.

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

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

The tool has zero parameters and schema description coverage is 100%, so there are no parameter semantics for the description to clarify. The baseline of 4 applies because there is nothing meaningful to add.

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 purpose: returning pre-analyzed financial observations ready to narrate, with each item containing a ready-made `text`. It enumerates the exact behavior patterns covered (weekday-by-category, post-income spending increase, weekend category rises) and explicitly distinguishes the tool from insights_highlight and specific anomaly tools, making the resource and 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?

The description gives clear when-not guidance by naming alternatives: insights_highlight for a single budget/delay-focused highlight, and bill_anomalies, transport_routine, bill_concentration, best_card_day, subscriptions_overview for isolated anomaly signals. This lets an agent route to the correct tool instead of behavior_insights.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds valuable behavior beyond annotations: the 15-day threshold, ignoring unconfigured cards, and returning an empty list when no card qualifies. It could also mention edge cases or errors, but this is solid 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?

Three compact sentences carry the full meaning: the core alert, the filter condition, and the empty-result behavior. The description is front-loaded and every sentence earns its place.

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

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

For a zero-parameter, read-only tool with no output schema, the description explains when it triggers, which cards are excluded, the threshold used, and the empty-list fallback. An agent has enough information to invoke the tool 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 input schema has zero parameters, so there is no parameter semantics to clarify. The description correctly implies that the tool derives its behavior from the user's card data rather than explicit arguments, matching the baseline 4 for zero-parameter tools.

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 warns the user, for each card, when today is the eve of invoice closing, and explains the practical benefit of postponing a purchase. This clearly distinguishes it from list_cards and other invoice-related sibling tools.

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

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

It clearly specifies the triggering condition (day before closing), the ≥15-day difference threshold, and the handling of cards without closingDay/dueDay. It does not explicitly name alternatives or state when not to use the tool, 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 already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral detail: the >20% threshold, the 6-month comparison window, the minimum historical occurrences requirement, empty-list behavior when nothing qualifies, and ordering by largest deviation. This goes well beyond the annotation 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 three sentences with zero waste. The core anomaly rule is front-loaded, followed by the exclusion condition and output ordering behavior. Every sentence carries essential, non-redundant information.

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

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

For a zero-parameter, read-only analysis tool with an output schema, the description is fully complete. It explains the detection rule, prerequisites, edge cases, ordering, and empty behavior. There is no missing information needed to invoke or 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 has zero parameters, so schema description coverage is 100% and no parameter documentation is needed. The description appropriately focuses on the tool's filtering semantics rather than parameters, matching the baseline for a no-parameter tool.

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 exactly what the tool does: it identifies active recurring expense bills whose latest posted occurrence this month exceeds the 6-month average by more than 20%. It gives concrete examples (rent, electricity), clear exclusion criteria, and output ordering, making it distinctly recognizable among sibling analytics 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 provides clear context for when to use it — for surfacing unusually high recurring bills in the current month — and defines qualifying conditions (active recurring expenses, at least 2 historical occurrences). It does not explicitly name alternative tools or state when not to use it, so it misses the full 5.

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

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

Annotations already declare readOnlyHint=true; the description goes further by disclosing the exact lookahead window, qualifying transaction types, the ≥35% concentration threshold, and the empty-list behavior when the threshold is not met. This is strong behavioral disclosure with no contradiction.

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 dense sentence that front-loads the primary objective, clearly defines the calculation inputs, and states the conditional return. Every clause adds necessary information; there is 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?

The description fully specifies the computation window, the types of commitments included, the threshold, and the empty-list fallback. Since an output schema exists, return-value details need not be repeated, and there are no parameters to document.

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

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

The tool has zero parameters and schema description coverage is 100%, so there is nothing for the description to add about parameters. The baseline of 4 applies.

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

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

The description states a specific action ('Acha'), a specific resource (5-day window within the next 30 days), and the exact composition of commitments. It also defines the threshold condition, making it clearly distinct from generic forecasting or anomaly-detection 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 makes the tool's scope and threshold clear, so an agent can infer when it is relevant. However, it never explicitly says when to prefer this tool over overlapping siblings like bill_anomalies, cashflow_forecast, or spending_projection, nor does it mention 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral details beyond annotations: the empty-list behavior for `daily`, the projection only for current-month MONTHLY budgets, and the transaction aggregation logic.

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 focused sentences cover the core comparison, period logic, aggregation rule, the `daily` field behavior, and the `id` disambiguation. No wasted words, and the most important semantic caveat is included up front.

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 a single parameter, a read-only annotation set, and an existing output schema, the description sufficiently explains the tool's behavior and edge cases. An agent has enough information to invoke it correctly without additional context.

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

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

Schema coverage is 100% with one parameter already described. The description adds meaningful semantic clarity by explicitly warning that `id` is the Budget id, not a category id, and by explaining how the budget period affects the aggregation.

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

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

The description clearly states the tool's function: comparing budgeted amount versus actual spending for one specific budget over its period. It also explicitly distinguishes the `id` as a Budget id, not a category id, which helps disambiguate this comparison tool from category-level analytics.

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

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

The description provides clear context on when to use the tool: for a specific budget and its configured period, with special handling for `daily` only in current-month MONTHLY budgets. It does not explicitly name alternative tools, but the scope is unambiguous enough for an agent to select it correctly.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds meaningful behavior beyond that: it defines the balance check as 'soma de contas não-cartão', the 12-month projection horizon, reuse of cashflow_forecast's materialized projection, detection of months becoming negative, and goal delay calculation. It also explicitly states 'Não grava nada'.

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

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

The description is dense but every clause carries load: what is simulated, the exact checks performed, the no-persistence guarantee, and the alternative tool when different scenarios must be modeled. It is structured with the core action first, followed by detail and routing.

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 a single well-documented parameter and an available output schema, the description provides all necessary context: scope of simulation, inputs it considers, time horizon, side-effect-free behavior, and when to use a different tool instead. Nothing essential is missing for correct invocation.

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

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

The schema already covers the single required parameter 'amount' completely with type and a constraint that it must be greater than 0. The description adds the framing of a one-time expense from today, but does not need to compensate for any schema gap, so a baseline score 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 opens with a specific verb and resource: 'Simula uma despesa única a partir de hoje' and then details exactly what is checked. The final sentence differentiates it from the sibling cashflow_forecast, so an agent can reliably select can_afford over 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 explicitly states that this is a read-only simulation and provides an exclusion condition: 'para comparar cenários de liquidação de ativo ou amortização de dívida use cashflow_forecast com liquidationParams/simulationParams'. This gives clear routing guidance versus the relevant sibling.

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

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

Beyond the readOnlyHint=true annotation, the description discloses meaningful dynamic behavior: it serves a cached/materialized read when includePending=true and no simulation is requested, otherwise recalculates live in the Python engine. It also explicitly states the simulation modes write nothing ('não grava nada, é só simulação'), which is consistent with — and adds depth to — the annotations. No contradiction with annotations.

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

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

The description is long but every sentence earns its place: core function, cache-vs-live behavior, simulation semantics, and sibling differentiation are each handled in one sentence. It is front-loaded with the primary purpose. Minor blemish: it refers to 'pending=true' where the actual parameter is 'includePending', which could cause a slight mismatch when an agent maps the description to 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 an output schema exists (so return values need not be explained), annotations cover the read-only safety profile, and the schema covers 100% of parameters, the description is very complete. It covers cache/live modes, both simulation types with non-persistence, and sibling differentiation. Only minor gaps remain, such as the parameter-name shorthand and no explicit mention of the 1-12 month constraint (left to 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?

Schema description coverage is 100%, so the schema documents all six parameters in detail (defaults, ranges, JSON shapes, validity conditions). The description adds the framing that simulation parameters impact the projected balance without persisting, and references the months cap, but most parameter semantics are already carried by the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: month-by-month projection of inflows, outflows, and projected balance ('Projeção mês a mês... de entradas, saídas e saldo projetado'). It also explicitly distinguishes itself from siblings, claiming to be the only tool that returns complete monthly cash/balance and naming spending_projection, networth_projection, current_month_spending, and analytics_history as 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 final sentence gives explicit routing rules: use spending_projection for expenses-only by category, networth_projection for net worth only, current_month_spending for the current month without future projection, and analytics_history for real historical series. This is direct when-to-use-vs-alternatives guidance tied to concrete sibling names.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds meaningful behavioral context beyond annotations: it sums subcategories, compares to the previous month, conditionally includes budget comparison, defaults to the current month, and switches between materialized and live calculation. This gives the agent a solid understanding of what the tool actually does at runtime.

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

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

The description is dense but efficient, front-loading the core purpose before moving to behavioral nuances and sibling alternatives. It could be slightly more scannable with separate sentences, but every clause earns its place and there is no redundant content.

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

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

Given the presence of an output schema, the description does not need to explain return values. It covers the comparison logic, aggregation, budget conditionality, default behavior, computation modes, and alternatives, leaving no significant gap for an agent to call this 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 100%, so the structured schema already documents year, month, and userId well. The description adds extra value by explaining the behavioral consequence of omitting month/year (materialized fast path vs. live calculation) and clarifies that omitting year uses the current year, complementing the schema defaults.

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: accumulated spend by category, compared with the previous month, including percentage change and budget comparison. It also explicitly differentiates itself from sibling tools by naming category_history, tags_insights, and financial_snapshot, so an agent can select the right tool without opening schemas.

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

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

The description provides explicit routing guidance: use category_history for multi-month series, tags_insights for tag-based insights, and financial_snapshot for correlation summaries. It also explains the materialized vs. live computation modes depending on whether month/year is supplied, which clarifies when each call mode is appropriate.

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

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

Annotations already mark readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable behavior: the series is historical and explicitly not a projection ('não projeção'), limited to top N categories by volume, and includes mean/median/standard deviation and trend. This goes beyond the annotations and clarifies what the agent should expect.

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

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

Two dense, efficient sentences: the first defines the output and its constraints, the second provides usage and alternatives. No filler or repetition; the core concept 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?

An output schema is present, so return values are already structurally documented. With no required parameters and all optional ones covered, the description provides purpose, scope, usage context, and alternative routing. Nothing essential for an agent to decide whether and how to invoke this tool 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 100%, so all three parameters already have descriptions including format (YYYY-MM or YYYY-MM-DD) for from/to and range plus default for top. The description adds only marginal semantic value by linking 'top' to 'top N categorias' and implying from/to define the analysis window. A baseline of 3 is appropriate.

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

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

The description opens by stating exactly what the tool returns: a monthly historical series (not a projection) broken down by category, limited to top N categories, with statistics and trend. It explicitly contrasts itself with analytics_history and categories_insights, so an agent can distinguish it from siblings without inspecting schemas.

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

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

The description gives an explicit use context: 'Use para sazonalidade/comparar categorias ao longo do tempo'. It then names two alternatives and the exact conditions for choosing them: analytics_history for the general total without category breakdown, and categories_insights for current vs previous month without a long series. This fully routes 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 only indicate the tool is not read-only, not idempotent, and not destructive. The description adds meaningful behavioral detail: balance validation is skipped, negative balances are permitted, card limit validation still applies, and certain parameters are unsupported. It does not fully enumerate all side effects, but for a mutation tool this is solid transparency.

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

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

The description is dense and well-structured: first the key differentiator, then the recommended use case, then exclusions. Every sentence adds value and there is no fluff. The most important behavioral caveat 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?

Given the high schema coverage, output schema, and available sibling create_transaction, the description is complete enough for correct invocation. It explains when to use it, what behavioral difference it has, which fields it does not support, and what should be used instead. The reliance on create_transaction for baseline behavior is acceptable because that sibling is available in the context.

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

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

Schema description coverage is 93%, and the schema already documents most parameters, so the baseline is 3. The description adds value beyond the schema by explicitly listing unsupported parameters (installments, scheduledDate, nature, ticker/exchange/shares), which helps the agent avoid invalid inputs. It also reinforces the semantic relationship with balance behavior, though it does not deeply explain every 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 clearly states the tool creates a transaction like create_transaction but without validating sufficient balance, expressly allowing negative balances. It distinguishes itself from its sibling by naming the exact behavioral difference and the unsupported fields. The purpose is unambiguous and tied to a specific verb and 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 explicitly says when to use this tool instead of create_transaction: when the user registers something knowingly leaving the balance negative, such as a retroactive statement import. It also gives explicit exclusions—no installments, scheduledDate, nature, ticker/exchange/shares—and directs the user to create_transaction for those cases. This is strong, actionable 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 mark this as a non-read-only, non-idempotent mutation. The description adds concrete behavioral details: sets paidDate, applies balance effect, does NOT affect card fields, and returns 400 on already-paid transactions. This enriches the annotation signals with actionable 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?

Two sentences, front-loaded with the main action and immediately followed by error and limitation caveats. No filler, no repetition of schema details, and every sentence earns its place.

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

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

For a single-parameter tool with an output schema, the description covers the operation, its side effects on balance, non-effects on card, and the 400 error case. It is fully sufficient for an agent 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?

The schema already documents the single 'id' parameter at 100% coverage with 'ID da transação pendente a confirmar'. The description adds value by explicitly defining what 'pendente' means (agendada ou isPaid: false), narrowing the acceptable input and connecting it to the balance effect.

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: 'Marca uma transação existente... como paga agora' and precisely defines the target state (agendada ou com isPaid: false). It also clarifies what it does not do (card effect), distinguishing it from sibling confirmation tools.

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

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

The description gives clear context for when to use the tool: for existing pending transactions only. It explicitly excludes already-paid transactions (returns 400) and card-affecting scenarios (no limitUsed/fatura effect). It does not name an alternative sibling, but the boundary is well-defined.

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 thin annotations (all false), the description discloses the most important behavioral trait: balance is the initial value and is later adjusted incrementally as paid transactions are created/confirmed/deleted. It also states the ownership/authentication context (authenticated user as OWNER), which is exactly the kind of context that helps an agent reason about 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?

Two sentences, with the main purpose front-loaded and the critical balance nuance in the second sentence. There is no filler; each sentence earns its place.

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

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

For a 7-parameter creation tool with a complete schema and output schema, the description covers the core purpose, ownership, and the one non-obvious parameter behavior. It does not explicitly cover usage boundaries versus sibling tools, but the schema and name make most of the remaining context unnecessary.

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 goes further by explaining the balance parameter's role as a starting point and how it evolves with transactions. This adds behavioral meaning beyond the schema property description and helps the agent supply a correct initial balance.

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 the specific action 'Cria uma conta bancária/carteira nova' and adds that the authenticated user becomes OWNER, which clearly identifies the resource and scope. The create/update/delete/list sibling cluster is easily disambiguated because 'account' is named explicitly as the new 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 implies the situation where it should be used: when a new account/wallet must be created for the authenticated user. However, it does not explicitly state when not to use it or name alternatives such as update_account for existing accounts, leaving the routing partly 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?

Beyond the annotations (readOnly=false, destructive=false), the description discloses an important side effect: recalculation of analytics and user insights. It also reveals harmful behavior when required fields are omitted — empty values break the join with budget_comparison — which is highly valuable for an agent.

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, well-structured sentences: the purpose comes first, followed by critical DB constraints and side effects, then sibling differentiation. Every sentence contributes value and the description remains compact.

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

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

The description, combined with a fully documented schema, an output schema, and annotations, covers all necessary aspects: what the tool does, critical constraints, side effects, and sibling distinctions. No meaningful information 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 100%, so the baseline is 3, but the description adds meaningful context about name and type: they are required in the database, have no default, and omitting them causes empty values and breaks transaction matching. This goes beyond the schema's required list and enum descriptions.

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

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

The description clearly states a specific action and resource: 'Cria um orçamento (limite planejado) por categoria e período.' It also explicitly differentiates itself from create_goal and create_debt, so an agent can distinguish this from similarly named budget/goal/debt creation 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 explicitly names alternatives (create_goal and create_debt) and explains what each is for, making it clear when not to use this tool. It also gives critical usage warnings about mandatory name/type fields and the consequences of omitting them, which is strong operational 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 establish that this is a non-read-only, non-destructive operation. The description adds behavioral context beyond the annotations by specifying that a newly created card starts with used limit and current invoice at zero and is scoped to the authenticated user. 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?

A single, front-loaded sentence that moves from action to resource to behavioral details without filler. Every clause earns its place: scope, resource type, and the zeroed initial state.

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 tool with an output schema, exhaustive schema descriptions, and safety annotations, the description covers the essential domain semantics that are not in structured fields. Explicit alternative routing is the only missing element, and that is already accounted for in usage_guidelines.

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 even without parameter information in the tool description. The description adds no field-level semantics, but the input schema fully documents all nine parameters, including requirements and defaults.

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 ('Cria'), a clear resource ('cartão de crédito'), and adds meaningful scope ('para o usuário autenticado') plus initial state details. This distinguishes it from sibling creation tools such as create_account, create_transaction, and update_card.

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 creating a new card for the authenticated user, but it never explicitly states when to choose it over alternatives like update_card/delete_card/list_cards. It provides no exclusions or alternative routing, so 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 carry almost no signal — all hints are false — so the description carries the behavioral burden, and it delivers: it discloses that the type is inherited from the global record when global IDs are supplied, that a divergent type triggers a 400 error, and that parentId requires matching types. This goes meaningfully beyond the structured annotation 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?

Two dense sentences with zero filler: the core purpose is front-loaded, followed by the subcategory rule and the global-catalog inheritance caveat. Every clause earns its place — the parentheticals carry real constraints rather than 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 tool with 7 parameters, 2 required, and an output schema present, the description plus the fully-covered schema provide a complete picture of the creation variants (plain category, subcategory, global-linked). Minor gaps remain — no mention of name-uniqueness constraints or subcategory depth limits — but nothing an agent needs to invoke 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 description coverage is 100%, so the baseline is 3; the schema already documents every parameter including the type-inheritance rule on the type field. The description adds some connective meaning (the parentId type-constraint and the 400-error consequence), but it mostly re-expresses what the schema already states, so no credit above baseline is warranted.

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+resource — "Cria uma categoria ou subcategoria do usuário" — and adds a distinguishing mechanism (parentId for subcategories), which separates it from siblings like create_transaction or create_account. The mention of the global catalog tie-in further narrows this tool's unique identity among the create_* family.

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 conditional usage context: when to use parentId (to create a subcategory), when to use globalCategoryId/globalSubcategoryId (to link to the global catalog), and the consequence of a type mismatch (400 error). It does not explicitly name alternatives like update_category or list_categories, but the create/update/list/delete split among siblings is self-evident, so the lack of exclusions is a minor 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 signal that this is a mutating, non-idempotent, non-destructive operation. The description adds meaningful behavioral context beyond those annotations by guaranteeing that a newly created cost center always has `isDefault` set to false, which an agent could not infer 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?

A single, clear sentence that states the action, the object, and the most important behavioral nuance with no wasted words. The key behavior is front-loaded and easy to parse.

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

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

This is a simple creation tool with only two parameters, one required, full schema descriptions, and an output schema present. The description plus annotations and schema cover all essential information an agent needs 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%, and both `name` and `description` are already described in the schema. The description does not add further parameter-level semantics, but it does not need to because the schema already carries the burden.

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

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

The description uses a specific verb ('Cria') and resource ('centro de custo novo'), and adds the key distinguishing trait that created cost centers are non-default with `isDefault` starting false. This clearly separates it from update, delete, and list 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 use case is implied by the verb and the word 'novo': create a new cost center rather than updating or deleting an existing one. However, the description does not explicitly state when to prefer this over update_cost_center or mention any prerequisites, so guidance remains 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 description discloses meaningful behavioral details beyond the annotations: equityId is validated to belong to the user before saving, with a specific 400 'Invalid equityId' error otherwise. It also explicitly warns about the side effect of recalculating analytics and insights, which is exactly the kind of non-obvious behavior an agent needs to know.

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 efficiently structured: a one-line primary purpose, then the most important conditional parameter behavior, then the side effect disclosure. Every sentence adds information not already available in the schema or annotations, 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 the tool's complexity (11 parameters, 2 required, a create operation with side effects) and the rich schema and output schema, the description covers the essential non-obvious aspects: equityId ownership constraints, the resulting error, and analytics/insights recalculation. Nothing critical for correct invocation appears to be 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?

With 91% schema description coverage, the schema already documents most parameters well. The description adds valuable semantic context for equityId by explaining ownership validation, the error case, and the asset-financed-by-debt relationship, going beyond the schema's brief field description.

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

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

The description opens with a specific verb and resource: 'Registra uma dívida do usuário' (records a user's debt), making the tool's core action immediately clear. It also adds distinguishing details like the equityId financing relationship, which separates this create-debt operation from generic transaction or account creation 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 clearly implies this is for registering a new debt, and the presence of update_debt/delete_debt siblings makes the create-vs-update distinction inferable. However, it never explicitly states when to choose create_debt over update_debt or how to handle an existing debt, so the guidance remains 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?

As annotations são todas negativas/falsas e não informam os comportamentos relevantes. A descrição adiciona contexto valioso: atomicidade da operação, criação simultânea da primeira EquityValuation com value/cost/data e recálculo best-effort em background. Não há contradição com as 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?

Duas frases objetivas: a primeira entrega a função central e a atomicidade; a segunda adiciona o efeito assíncrono. Não há palavras redundantes nem informações desnecessárias. A estrutura é front-loaded e eficiente.

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?

Com 10 parâmetros, schema 100% coberto, output schema presente e annotations fornecidas, a descrição cobre os comportamentos não óbvios: operação atômica, primeira avaliação e recálculo em background. A não idempotência é sinalizada por idempotentHint=false, então não é uma lacuna. Nada essencial falta para o agente invocar corretamente.

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?

O schema cobre 100% dos 10 parâmetros com descrições próprias, então o baseline é 3. A descrição apenas menciona que value/cost/data alimentam a primeira avaliação, sem acrescentar detalhes além do schema. Ela não compensa nem contradiz as definições paramétricas já existentes.

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?

A descrição é específica: cria um ativo de investimento (Equity), registra a primeira avaliação (EquityValuation) no mesmo statement atômico e dispara recálculo em background. Isso a distingue claramente de add_equity_valuation, update_equity e list_equities. Não há ambiguidade sobre o recurso ou a ação.

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?

A descrição posiciona a ferramenta em relação a add_equity_valuation: criar o ativo e já chamar add_equity_valuation uma vez é equivalente a este tool. Isso indica que avaliações subsequentes devem usar add_equity_valuation, mas não há uma regra explícita de quando não usar. A orientação é clara, porém implícita.

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 (which only indicate non-read-only and non-idempotent), the description discloses a critical database behavior: category and color are required at the DB level but get silently stored as empty strings if omitted, with a recommendation to always provide them. It also explicitly states that no analytics/insights recalculation is triggered, a useful side-effect trait for the agent.

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: purpose first, then a critical behavioral warning, then a differentiation note. Every sentence adds distinct value with no repetition or 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 the presence of a complete input schema and output schema, the description covers the essential operational nuances not evident from structured data: the DB-level required fields and the absence of analytics recalculation. An agent has enough context to invoke the tool correctly without needing additional details.

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

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

Schema description coverage is 100%, so all seven parameters are already documented with meaningful descriptions. The tool description mostly repeats the category/color DB-required caveat already present in the schema, adding only the advice to prefer providing them. Since the schema carries the heavy lifting, a 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 ('Cria') and resource ('meta financeira') with concrete examples ('Viagem', 'Reserva de emergência'). It also differentiates from create_budget and create_debt by noting the analytics recalculation difference, making the tool's scope clear even among many create_* siblings.

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

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

The description explicitly names create_budget and create_debt as alternatives in the context of analytics recalculation, providing a clear criterion for choosing this tool over those when no recalculation is desired. It does not, however, explain the broader semantic differences between a goal, budget, and debt, so some inference is still required.

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 all false, so the description carries the full burden for behavioral disclosure. It reveals that past-dated occurrences become paid and immediately affect balance, future ones are pending, and card invoices are created for EXPENSE occurrences when cardId is supplied — exactly the non-obvious side effects an agent needs to know.

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 with no filler: the core behavior, default endDate, payment status split, card invoice behavior, and the categoryId contrast are each presented once and all earn their place. Key information is front-loaded.

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

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

With an output schema available, return-value explanation is unnecessary. The description covers the non-obvious behaviors (immediate balance impact, pending future occurrences, card invoice creation, category free-text semantics) and leaves field mechanics to the fully described schema, making it complete for a 12-parameter create 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%, so the baseline is 3. The description adds value by explaining the temporal consequence of startDate/endDate (past occurrences paid, future pending) and reinforcing the cardId invoice behavior beyond the raw field 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 action ('Cria uma regra recorrente e, de uma vez, já gera todas as transações concretas entre startDate e endDate') and explicitly distinguishes RecurringTransaction from Transaction by noting the absence of categoryId. This makes the tool's purpose unambiguous and separable from sibling 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?

It gives clear context for when to use the tool and directly contrasts with Transaction, signaling that if a real category FK is needed, the one-off Transaction tool is the alternative. It does not explicitly enumerate all when-not scenarios, but the distinction is enough to route an agent correctly.

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

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

Annotations already mark this as non-read-only, non-idempotent, and non-destructive. The description adds a non-obvious behavioral caveat: 'Não valida duplicidade de nome', which tells the agent duplicate names are allowed and not rejected. It also scopes the operation to the authenticated user's transactions.

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 in Portuguese, front-loaded with the action and followed by the one caveat that matters. 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 creation tool with output schema and safety annotations, the description covers the essential behavior. It could additionally direct the agent to list existing tags when uniqueness matters, but that is a usage-guidance enhancement rather than a blocker.

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 schema already documents both parameters. The description adds one meaningful parameter-related fact: the `name` field is not validated for duplicate, so the agent should not assume uniqueness. This goes beyond the schema's plain type/description.

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

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

The description uses a specific verb and resource: 'Cria uma nova tag para marcar transações do usuário autenticado.' It clearly identifies what is created and for whom, and the resource 'tag' distinguishes it from sibling tools like create_category and 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?

No guidance on when to prefer this tool over alternatives is given. It does not mention checking existing tags with list_tags before creating, nor any condition that would rule this tool out. The duplicate-name warning is behavioral, not usage 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 are minimal (all flags false), so the description carries the burden — and it delivers: validation failure mode with 400 on insufficient balance/limit, conditional validation gated on isPaid and scheduledDate, side effects (best-effort recalculation of projections/insights, budget push alert), and per-parameter behavioral branching (installments generating future occurrences, Equity create/update with a default fallback, goal progress on TRANSFER). Nothing contradicts 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?

A single dense paragraph of roughly 170 words with zero filler — every clause carries semantic weight, and the core action plus required-field note come first. However, the density hurts scannability: the investment/Equity portion stacks multiple conditionals into one sentence, and bullet structure would make the conditional behaviors easier for an agent to parse.

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

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

For a 20-parameter tool with an output schema present, the description covers the cross-cutting behaviors that the flat schema cannot convey: validation gates, scheduling semantics, installments, Equity creation/update with default fallback, goal interaction, and post-creation side effects. Only minor edge cases are uncovered (e.g., both accountId and cardId supplied together), and those are marginal given the rich schema and output schema.

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

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

With 95% schema coverage, the baseline is 3 and the schema already documents most parameters. The description adds genuinely cross-parameter semantics the flat schema cannot express: the accountId XOR cardId requirement summarized, the isPaid × scheduledDate gate that toggles fund validation, the amount/installments relationship, and the default 'Investimentos Gerais' Equity fallback that appears nowhere 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 opens with a specific verb and resource — 'Cria uma transação (EXPENSE/INCOME/TRANSFER)' — and immediately delimits scope: a single transaction of three possible types. It semantically separates from the confirm_* siblings (which confirm rather than create) and from create_recurring_transaction (which creates a recurring pattern rather than a single transaction with installments).

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 names alternatives with conditions: 'para permitir saldo negativo use confirm_new_transaction' and the scheduling flow that later routes to confirm_pending_transaction. However, it gives no guidance about when to prefer create_recurring_transaction — the closest sibling, also a transaction-creating tool — nor about update/delete fallbacks.

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 carry readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond those: the strict current-month scope, the fact that projections include a confidence level, and the conditional budget comparison ('se houver'). No contradictions with annotations.

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

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

A single dense sentence front-loads the critical scope constraint, then lists the computed outputs, then states exclusions. Every clause earns its place: nothing is filler, and the sibling differentiation is packed into the trailing clause without bloating the text.

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

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

For a read-only analytics tool with an output schema present, the description covers everything needed: scope limitation, the set of computed values, the conditional budget comparison, and sibling differentiation. Return structure is already handled by the output schema, so no additional information is missing.

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

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

Schema description coverage is 100%: both userId (client id for financial planner use, defaults to authenticated user) and topCategories (count range 1-20, default 5) are fully documented in the schema. The description adds no parameter-specific information, so the baseline of 3 applies — the schema carries the heavy lifting.

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 resource (current month spending) and enumerates exactly what is computed: realized spending, daily pace, projected total to end of month, projection confidence, and budget comparison when a budget exists. It also bounds the scope with 'Só o mês corrente (não série futura)' and explicitly contrasts itself with three sibling tools, so an agent can distinguish it without opening any 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 explicitly names alternatives and the condition that selects them: cashflow_forecast/spending_projection for multi-month forward looks, and categories_insights for month-over-month category comparison without pace/closing projection. An agent deciding between these tools has clear routing criteria and no inference is required.

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

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

Beyond the readOnlyHint/destructiveHint annotations, the description discloses that nothing is persisted, the exact computed outputs (monthly amount, total paid, total interest, projected balance impact including negative months), and the simulation nature. It reinforces and expands on 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?

Two dense sentences carry purpose, input rules, output summary, and the alternative tool. The most important scoping information (simulation, one debt, exclusive parameters) is front-loaded, and every phrase 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 read-only simulation with an output schema, the description covers what the tool does, what inputs are allowed, what it returns, and what to use instead for real changes. An agent has everything it needs to invoke it correctly and avoid confusing it with update_debt.

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 schema already documents all three parameters. The description adds real value by explaining the mutually exclusive relationship between targetMonths and monthlyPayment, and by linking each one to its computed result, 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?

The description opens with a specific verb and resource: 'Simula a quitação de UMA dívida' (simulates paying off one debt), and immediately clarifies it is a simulation, not an actual write. It distinguishes itself from update_debt by name, so an agent can tell planning from execution.

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 states the two possible input modes (targetMonths OR monthlyPayment), forbids using both ('nunca os dois'), and tells the agent to use update_debt(remainingAmount) instead when the goal is to actually reduce the balance. This gives clear when/when-not 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?

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description reveals that deletion is permanent and irreversible, that there is no extra confirmation step, and that linked transactions/cards are not checked before deletion. This is meaningful behavioral context an agent needs to warn the user or set expectations.

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, each earning its place: the action and permanence, the permission restriction and sibling contrast, and the missing safety checks. The most important information is front-loaded.

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

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

For a single-parameter destructive tool with full schema coverage, an output schema, and annotations already covering side effects, the description provides all essential context: who may call it, what it does, and what it does not do. Nothing critical 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 `id` parameter is already described as "ID da conta a excluir." The description mentions `userId` in an authorization context but does not add further semantic detail about the parameter itself. Baseline 3 is appropriate given the high schema coverage.

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

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

The description opens with "Exclui uma conta permanentemente," which names a specific verb (delete), a specific resource (account), and the key property (permanently). It also differentiates itself from update_account by stating that joint account members can edit but cannot delete.

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 states who is allowed to use the tool: only the account owner, identified by `userId`. It also gives a clear when-not condition: joint account members cannot delete even though they can edit via update_account, naming the alternative tool directly.

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 (destructiveHint=true, idempotentHint=true), the description discloses two important behavioral details: it recalculates user analytics and insights, and it does not delete or unlink transactions compared against the budget. This adds meaningful context about side effects and non-effects, which is exactly what an agent needs.

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

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

The description is two short sentences, front-loading the primary action and immediately following with the most critical side effects. Every sentence adds value and there is no redundant wording.

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 a single documented parameter, output schema present, and annotations covering safety and idempotency, the description covers the remaining behavioral context (side effects and what is not affected). Nothing essential is missing for an agent 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 100%, and the single parameter 'id' is fully described in the schema as the budget ID to delete. The description adds no additional parameter-level meaning, so baseline 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 uses a specific verb ('Exclui') and resource ('orçamento'), clearly identifying what the tool deletes. It implicitly differentiates from sibling tools like create_budget, update_budget, and list_budgets by stating the delete operation on the exact 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 usage context is implied: use this when you need to delete a budget. However, the description does not explicitly state when to use this tool over alternatives, nor does it mention any exclusions or prerequisites. It provides no direct routing guidance among the budget-related sibling 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?

Beyond the destructiveHint annotation, the description adds important behavioral context: deletion is permanent and no validation is performed for open invoices or linked transactions. This gives the agent a clear picture of consequences not inferable from annotations alone.

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

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

Two concise sentences cover the action, permanence, and a key warning. There is no redundant or vague text, and the most important information is front-loaded.

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

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

For a simple one-parameter destructive operation with an output schema and clarifying annotations, the description is complete. It covers what is deleted, that it is permanent, and the risk of unverified linked data, leaving no critical gap for correct invocation.

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

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

The input schema fully documents the only parameter 'id' with 'ID do cartão a excluir'. The description adds no extra meaning about the id's format or how to determine the correct value, so it does not meaningfully improve on 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 action and resource: 'Exclui um cartão de crédito permanentemente' (permanently deletes a credit card). This clearly distinguishes it from sibling tools like update_card and list_cards.

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 when a card must be permanently deleted and warns that no invoice or transaction checks occur. However, it does not explicitly state when to prefer this tool over alternatives or mention any conditions 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 indicate destructive and idempotent behavior, but the description adds important non-obvious details: there is no verification of linked transactions/budgets before deletion, and child subcategories are not cascade-deleted. This goes beyond what annotations alone provide.

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

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

The description is two short, purposeful sentences. The main behavior is front-loaded, and the critical caveats about linked data and subcategory handling are stated without unnecessary 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 operation with an output schema and strong annotations, the description covers the essential behavioral context: permanence, absence of validation, and non-cascade behavior. It does not explain what happens to orphaned subcategories, but the other structured information reduces that burden.

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

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

The schema already covers the only parameter 'id' with a description, so the baseline is 3. The tool description confirms that the id may refer to a category or subcategory but does not add deeper semantic detail beyond 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 opens with 'Exclui uma categoria (ou subcategoria) permanentemente,' which clearly states the specific action, resource, and scope. It also clarifies that subcategories are included, distinguishing it from broader or sibling 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 purpose statement makes it clear that this tool is used when a category or subcategory should be removed. However, it does not explicitly mention alternatives like update_category or create_category, nor does it state conditions for when this tool should not be used.

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, the description discloses two important behaviors: the operation is permanent, and there is no validation of linked transactions/recurrences before deletion. This is exactly the kind of safety-critical behavioral context an agent needs before calling a destructive 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?

Two sentences, front-loaded with the core action followed by essential caveats. Every sentence adds value and there is no redundant or vague wording.

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 tool with an output schema, the description covers the action, irreversibility, a critical error condition, and the lack of referential checks. Nothing essential is missing for an agent to decide whether and how to invoke it.

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 already fully documents the single `id` parameter with 100% coverage. The description does not add extra parameter-level detail, 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 clearly states a specific action ('Exclui permanentemente') on a specific resource ('centro de custo'), and adds distinguishing details like the default cost center protection. It is unambiguous and immediately differentiates this deletion tool from update or list cost center 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 provides clear context for when deletion is allowed: it will fail for the default cost center, and it warns that linked transactions/recurrences are not checked. It doesn't explicitly name alternative tools, but the usage conditions are strong enough to guide an 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?

The description explicitly discloses a side effect beyond the annotations: deleting a debt recalculates analytics (net worth) and user insights. This complements the destructiveHint and idempotentHint annotations with additional consequence information, though it does not detail the exact output.

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

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

The description is two short sentences with no filler: the primary action comes first, followed by the key side effect. 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 the simple single-parameter tool, an output schema, and annotations covering destructive/idempotent behavior, the description is nearly complete. The only small gap is the absence of explicit usage guidance, but the core purpose and side effects are fully 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 100%, with the single id parameter already documented as 'Id da dívida (Debt) a excluir'. The description adds no new parameter-level meaning, so the baseline of 3 applies.

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

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

The description opens with 'Exclui uma dívida', a specific verb and resource that clearly identifies the operation as deleting a debt. This differentiates it from sibling delete_* and update_debt tools by naming the exact resource affected.

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 verb 'Exclui' and the resource, so an agent can infer this is for removing debts. However, there is no explicit statement about when to prefer this over alternative tools such as update_debt or delete_transaction, or 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?

The description goes well beyond the destructiveHint annotation by disclosing that deletion is permanent, related transactions remain but become orphaned, EquityValuation history is removed via cascade, and count returns 0 without error when the id does not exist or is not owned by the user.

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 two most important consequences and an edge-case behavior. 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?

With one simple parameter and an output schema present, the description fully covers the tool's behavior: what is deleted, what is preserved, what is cascaded, and how missing or unauthorized ids are handled. No critical context 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 schema already fully documents the id parameter, so the baseline is 3. The description adds meaningful semantics: the id must belong to the user, and nonexistent or unauthorized ids produce a silent count of 0 rather than an error.

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 permanently deletes an investment asset belonging to the owner user. It clearly distinguishes itself from sibling tools like update_equity and list_equities by emphasizing permanence and the delete action.

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

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

The intended use is clear: call this when permanently removing an investment asset. It does not explicitly name alternatives or exclusions, but the ownership condition and the no-error behavior for missing ids provide sufficient context for when this tool applies.

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, and the description builds on them by disclosing irreversibility ('permanentemente') and the side-effect that Transaction.goalId becomes orphaned. This adds genuine behavioral context beyond what annotations 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?

Two short sentences with the primary action front-loaded and the critical side-effect second. There is no filler or repetition of the input 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 one-parameter delete operation, the definition supplies the irreversible behavior, the scope ('do usuário'), and the important consequence for linked transactions. Combined with the annotations and full schema coverage, nothing essential is missing to invoke this 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 100%: the schema already documents 'id' as 'Id da meta (Goal) a excluir'. The description adds no parameter-level detail, so it neither improves nor harms the schema's baseline.

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 ('Exclui permanentemente uma meta') and adds a meaningful behavioral qualifier ('Não afeta transações já vinculadas'), so an agent can tell this is a goal-deletion operation distinct from deleting transactions. It does not explicitly reference sibling tools, so it stops short of the strongest differentiation.

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

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

The sentence 'Não afeta transações já vinculadas a ela' gives clear decision-relevant context: use this when the goal should be removed but its linked transactions must be preserved. It does not spell out when-not-to-use or name an alternative like delete_transaction, so it lacks explicit exclusions.

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

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

Beyond the destructiveHint and readOnlyHint annotations, the description discloses the full cascade: it removes generated transactions including pending/future ones, unlinks card invoice associations, and reverses used card limits on already paid occurrences. It also explicitly states the action is irreversible. This goes well beyond what annotations already 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?

The description opens with the core destructive action and its scope, then adds the irreversibility warning and the safer alternative. Each clause contributes necessary information without redundancy or 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 destructive cascade operation with a single parameter, the description covers the full deletion scope, side effects on card limits, irreversibility, and the alternative. An output schema exists, so return-value details need not be explained in 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?

The single parameter id is already fully described in the input schema as the ID of the recurring rule to delete. The description does not add new parameter-specific semantics, but with 100% schema description coverage, the schema carries the burden adequately.

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 identifies the specific action: removing a recurring rule and ALL transactions it generated, including future/pending ones and card invoice links. It also clearly distinguishes this from the sibling update_recurring_transaction by naming it and explaining what it does differently. An agent can confidently select this tool for full deletion.

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 states when to use this tool: when the recurring rule and its generated transactions should be removed entirely. It also provides the alternative: use update_recurring_transaction with isActive: false if only future generation should stop without deleting history. This is direct, actionable 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?

The description adds meaningful behavior beyond the annotations: deletion is permanent, transactions are only affected by removing the tag reference via N:N cascade, and a non-existent or unauthorized id returns count 0 without error. This directly explains what gets destroyed and how failures behave.

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

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

The description is three tight sentences, each adding distinct value: the core action, the cascade effect, and the edge-case behavior. No filler or redundant explanation is present.

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

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

For a single-parameter deletion tool with annotations and an output schema, the description covers the essential operating details: permanent deletion, cascading effects, and response behavior for invalid or unauthorized ids. Nothing critical 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 id is already documented in the schema. The description repeats that id identifies the tag, which adds little beyond what the schema provides, 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 clearly states a specific action — permanently deleting a tag by its id — and distinguishes this tool from other delete_* siblings by naming the resource and the permanent nature of the operation. It also explains the cascading relationship with transactions, which adds precision beyond the tool name.

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 intended use is clear: call this when a tag should be permanently removed. While it does not explicitly name alternatives like update_tag for editing or list_tags for viewing, the context makes the appropriate usage obvious and there are no ambiguous 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?

Goes well beyond the annotations. destructiveHint=true only flags destructiveness, while the description details exactly what is reverted — account balance (and destination account if TRANSFER), linked goal if TRANSFER with goalId, card/invoice effect if cardId — conditioned on isPaid: true, and closes with 'Ação irreversível.' This is precisely the side-effect context an agent needs to predict the consequences of the call.

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 dense sentence that front-loads the primary action and then lists structured conditionals. Every clause earns its place — no filler — but the run-on structure with nested qualifiers ('se TRANSFER', 'se TRANSFER com goalId', 'se cardId') is heavier to scan than a short bulleted breakdown would be.

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

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

For a single-parameter destructive tool, coverage is strong: the operation, the conditional side-effect cascade, and irreversibility are all present. The remaining gaps — behavior when the id does not exist or was already deleted, and return values — are largely covered by annotations (idempotentHint=true) and the output schema respectively.

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%: the single 'id' parameter already has a description ('ID da transação a excluir'), so the baseline of 3 applies. The description adds only indirect meaning by tying the id to transaction properties (isPaid, TRANSFER, goalId, cardId) that modulate behavior, but does not further define the parameter itself.

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 — 'Exclui uma transação permanentemente' — making the operation unambiguous. The detailed cascade of reversals (balance, destination account, goal, card/invoice) clearly distinguishes it from siblings like update_transaction, create_transaction, and the confirm_* tools. The irreversibility warning 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?

Usage is implied rather than stated: the name and behavioral detail make clear this is for permanently removing transactions, but the description gives no explicit when/when-not guidance or named alternatives. It does not tell the agent when to prefer update_transaction or confirm_* tools over deletion, nor mention any 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?

The annotations declare readOnlyHint=true and destructiveHint=false, and the description builds on that by explaining the data source, best-effort recalculation behavior, and the on-the-fly computation when the snapshot is missing. This adds meaningful behavioral 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 well-structured and front-loaded: it opens with 'Retrato único do momento atual (não série)', lists the metrics, explains the materialized source, and closes with the key contrast to analytics_history. Every sentence adds distinct 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?

With no parameters, a read-only annotation, and an output schema available, the description provides all necessary operational context: it explains what is returned, how freshness works, what happens when the snapshot is missing, and how it differs from the main sibling tool.

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

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

The tool has zero parameters, so there is no parameter semantics to document. Per the baseline for a 0-parameter tool, the description appropriately focuses on what the snapshot contains rather than parameter 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?

The description clearly identifies a specific verb+resource: it provides a single current snapshot of financial status with a concrete list of metrics. It explicitly distinguishes itself from analytics_history by contrasting '1 number per metric (the state now)' with a monthly series, so an agent can tell them apart.

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 exactly when to use the tool: when the current financial state is needed, not a historical series. It names the alternative analytics_history and explains the key distinction, providing both a positive and negative 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 readOnlyHint=true and destructiveHint=false, and the description adds valuable context: id is the CreditCardInvoice id, not the card id, and fullTransactions carry category/installment details. This goes beyond the structured hints 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?

Two concise sentences that front-load the returned content and then add the critical id disambiguation and sibling routing. No filler, no repetition of 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-required-parameter read operation with an output schema available, the description covers everything needed: what the tool returns, how to interpret id, and which sibling to use when the id is unknown. Nothing critical 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 schema already describes id as 'Id da fatura (CreditCardInvoice)' with 100% coverage, so the baseline is solid. The description adds extra meaning by warning that id is not the card id and giving a fallback tool when only the card is known.

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: getting the full detail of a specific credit card invoice, enumerating the returned content (card data, transaction links, full transactions with category/installment fields). It also distinguishes itself from invoice_for_period by clarifying the id semantics, so an agent can tell them apart.

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 states when not to use this tool: when trying to fetch the active invoice of a card without knowing the invoice id, use invoice_for_period instead. This gives the agent a clear routing decision and names the alternative directly.

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

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

Annotations already signal read-only and non-destructive behavior, and the description adds a valuable behavioral detail: the phone field is redacted server-side and will never be returned even if requested. This goes beyond the structured metadata and prevents the agent from expecting data that will never exist.

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 dense sentence delivers the resource, the full field list, and the key redaction caveat with no filler. Information is front-loaded and the caveat is logically appended without bloating the description.

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 no-parameter read-only tool with an output schema available, the description is complete: it identifies the target user, lists the returned data, and states the one notable omission. Nothing else is needed for an agent 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 tool has zero parameters and the input schema coverage is 100%, so there is no parameter documentation burden on the description. The description appropriately focuses on the return payload instead of inventing parameter 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 ('Retorna') and a well-defined resource: the complete profile of the authenticated user, enumerating the exact data groups returned (registro, negócio, plano/assinatura, plannerId). This makes it unmistakably distinct from the sibling update_profile and other read-only 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 makes clear this is the tool for fetching the authenticated user's full profile, and the read-only naming reinforces when it applies. It does not explicitly name alternatives or exclusion cases, but for a zero-parameter getter the intended context is clear.

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