MoneyMatter

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

With no annotations, the description must carry the behavioral load, and it does well: it discloses the mutation effect (transactions linked to the tracker), the ownership constraint on trackerId, and the atomic-ish failure condition ('fails if any is not pending'), plus the returned field resolvedCount. It does not describe auth scope beyond ownership, rate limits, or whether the failure rolls back all links, leaving some gaps.

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, front-loaded with the action and effect, then provenance of ids, then failure/return behavior. 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 two-parameter mutation with no output schema and no annotations, the description covers effect, provenance, failure condition, and return value. Remaining gaps are secondary (rollback semantics, explicit alternative tool) rather than things an agent needs 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 both parameters are documented in the schema, so the baseline is 3. The description's note that ids come from list_tracker_suggestions and that trackerId must be owned mostly restates what the schema already says, adding little beyond it.

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 (accept) plus resource (pending smart-tracking suggestions of a tracker) and the side effect (each suggested transaction is linked to the tracker). It is clearly distinguishable from the sibling list_tracker_suggestions (which supplies ids) and reject_tracker_suggestions (implied opposite).

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?

Tells the agent where the suggestion ids come from (list_tracker_suggestions) and the precondition for success (all must be pending, otherwise the call fails). It stops short of explicitly naming reject_tracker_suggestions as the alternative for declining, so it is clear context rather than full when/when-not 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?

No annotations, so the description carries the full burden and does a solid job: it discloses an automatic side effect ('Transfer pairs are auto-included'), an auth requirement ('Requires finance:write scope'), and return behavior. Gaps remain — no mention of validation errors, duplicate handling, or partial-failure behavior for the array input.

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

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

Three short, front-loaded sentences with zero filler. The core action leads, followed by the non-obvious side effect, return shape, and auth need — 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 simple two-parameter mutation with no output schema, the description covers the return value, an automatic side effect, and the auth scope. Only behavioral edge cases (idempotency, error conditions) are absent, which is a minor gap.

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

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

Schema description coverage is 100% and both parameters are documented in the schema (groupId, transactionIds). The description adds only the cardinality hint 'one or more', which is already captured by the array type, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Add one or more transactions to an existing transaction group.' The resource naming naturally separates it from add_transactions_to_budget and remove_transactions_from_group, but it never names those siblings explicitly, so differentiation rests on the reader's inference.

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

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

The phrase 'existing transaction group' implies a prerequisite and the resource scoping implies usage, but there is no explicit when-to-use, when-not-to-use, or alternative pointer (e.g., add_transactions_to_budget vs this). An agent must infer the choice from the resource name alone.

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

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

With no annotations, the description carries full behavioral burden. It discloses an important side effect (category and tag rules also add links) and mentions a success message return, but omits permission requirements, idempotency, and handling of already-linked 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 sentences with zero waste: first states the action, then the side effect and return behavior. Information is front-loaded and appropriately sized.

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

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

Given no output schema and no annotations, the description should ideally explain return values and failure modes more thoroughly. It provides the key side-effect context but leaves the 'success message' vague and omits permission or error behavior, so it is only minimally adequate.

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 both parameters are fully documented in the schema. The description adds no extra parameter meaning beyond saying 'one or more transactions' and 'a tracker', 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 (manually link) and resource (one or more transactions to a tracker). The word 'manually' implicitly distinguishes this from automatic suggestion acceptance (accept_tracker_suggestions), but it does not explicitly name any sibling tool.

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

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

The description implies usage through 'manually link' but provides no explicit when-to-use or when-not-to-use guidance. It does not name alternatives such as accept_tracker_suggestions or link_transactions_to_subscription, leaving routing 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?

With no annotations, the description carries the full burden, and it does disclose the key side effect (a transaction is created for the diff) and the no-op case (transaction is null when already at target) — a genuinely useful behavioral detail. It omits permission/auth requirements, whether investment or archived accounts are rejected, and whether the generated transaction is reversible or categorized.

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

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

Two tight sentences: the first gives the operation and mechanism, the second gives the return shape. Front-loaded and every clause earns its place.

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

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

Because there is no output schema, the description's explicit return-value sentence is doing real work and covers the null case. What remains thin is account-type/eligibility context for a mutation tool with zero annotations, but for a 3-parameter tool this is close to complete.

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

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

Schema coverage is 100%, so all three parameters are already documented in the schema, including the note field and the decimal example for newBalance. The description restates the diff-based semantics of newBalance but adds no new format or constraint detail, so baseline 3 applies.

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

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

States a specific verb and resource (set an account to a specific balance) plus the mechanism used (an adjustment transaction for the difference), which clearly separates it from plain create_transaction or update_transaction. It never names a sibling, so the differentiation is implied rather than explicit.

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

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

The description implies the use case (getting an account to a target balance) and hints at an alternative path via 'adjustment transaction', but gives no explicit when-to-use/when-not-to guidance, no prerequisites (account must exist, be non-investment, etc.), and no 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?

With no annotations, the description carries the full behavioral burden. It discloses two important side effects: removal from groups and unlinking of subscriptions. However, it does not state whether the operation is reversible or what permissions are required, leaving gaps for a destructive mutation.

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 tightly written sentences, front-loaded with the core action, then the side effects, then the reverse case. 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?

For a two-parameter mutation with no annotations and no output schema, the description covers the essential effects but omits permission requirements, reversibility details, and any return-value information. It is adequate but not complete.

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

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

The schema documents both parameters fully, including the boolean semantics of 'archived'. The description reinforces the false case with 'restore to active status,' adding a small amount of clarity about the unarchive effect, though it does not give new syntax or format 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 clearly states a specific verb and resource: 'Archive or unarchive a user account.' The title is null, so there is no redundancy there. However, it does not distinguish itself from the sibling archive_budget, which uses an analogous archiving operation.

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

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

The description implies usage through the archived parameter ('Set archived=false to restore'), but it provides no explicit when-to-use guidance or exclusions relative to alternatives. No sibling tool is named or contrasted.

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?

With no annotations, the description carries the full burden. It discloses the concrete state change ("sets status to 'archived'"), the reversibility of the operation, and that the updated tracker is returned. It does not mention permission/auth requirements, side effects on the tracker's linked transactions or lines, or any rate limits.

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 short sentences, front-loaded with the action, then the parameter mechanic, then the return value. Efficient overall, though the isArchived explanation partially duplicates what the schema already states.

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

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

For a two-parameter toggle with no output schema, the description is nearly sufficient: it covers the operation, the boolean meaning, and the returned value. It omits the side-effect scope (what archiving does to associated transactions/lines) and any auth context, which would round it out.

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 parameters already document themselves (trackerId = ID of the tracker, isArchived = true to archive / false to restore). The description's restatement of the isArchived semantics adds no meaning beyond 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 pair and resource: "Archive or unarchive a tracker." An agent immediately knows this is a reversible state toggle on a tracker, not a delete. However, it never names or distinguishes itself from close siblings such as delete_tracker, update_tracker, or archive_account, which is what a 5 would require.

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 through the boolean semantics (true = archive, false = restore), which is enough to invoke the tool, but there is no guidance on when to prefer this over delete_tracker or update_tracker, and no prerequisites or exclusions are stated.

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

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

With no annotations present, the description carries the full burden and does well on the mutation semantics: it discloses that duplicate assignments are silently skipped (idempotent-ish behavior) and that the response contains added/skipped counts. It does not cover permission requirements, whether the tag must exist, or whether assigning tags triggers transaction automations.

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 short sentences, zero filler, with the core action stated first and the behavioral caveats and return shape following. Nothing needs to be trimmed.

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

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

For a two-parameter mutation with no annotations and no output schema, the description supplies the key facts an agent needs: the duplicate-skip behavior and the return counts. Remaining gaps are permission/prerequisite details and the absence of any alternative-tool routing.

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 parameters are documented in the schema, so the baseline is 3. The description adds the "existing tags" constraint on tagId but no format or cardinality detail beyond what the schema already provides.

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

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

States a specific verb (assign) and resource (tags on a transaction), which cleanly separates it from siblings like remove_tags_from_transaction and add_transactions_to_group. The framing is slightly inverted versus the schema (one tagId applied to many transactionIds, not many tags to one transaction), which is a minor inaccuracy but does not obscure the purpose.

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

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

"Use when the user wants to label a transaction with existing tags" gives a clear trigger condition and implicitly signals that the tag must already exist. It stops short of naming alternatives (remove_tags_from_transaction) or stating exclusions, so it is clear context without full routing guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It says the tool updates transactions in bulk and supports tag add/remove/replace, but it does not disclose permissions, partial-failure behavior, max batch size, reversibility, or return behavior, which are important for a bulk mutation.

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 compact sentences with no filler. The purpose is front-loaded, followed by the required parameter combination and tag-mode behavior.

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

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

For a bulk mutation with no annotations and no output schema, the description covers purpose, required fields, and tag modes, but leaves out operational details such as batch limits, failure handling, and return shape. It is adequate but incomplete for an agent deciding whether and how safely 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?

Schema coverage is 100%, so the baseline is 3. The description adds a meaningful cross-field constraint not expressed in the schema: transactionIds must be supplied together with at least one of categoryId, tagIds, note, or payeeId.

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: update multiple transactions at once. The bulk scope distinguishes it from single-transaction siblings such as update_transaction, and it lists the fields that can be changed.

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

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

It gives a clear invocation rule: provide transactionIds plus at least one of categoryId, tagIds, note, or payeeId. It does not explicitly name when to use this versus update_transaction or the tag-specific sibling tools, so it lacks exclusion guidance.

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

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

With no annotations, the description carries the full burden and discloses important behavior: the URL is short-lived, reusable across multiple files until expiry, and requires an HTTP-capable client. It does not mention authentication scopes, error handling, or upload side effects, which keeps it from a 5.

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

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

The description is front-loaded with the tool's purpose, then efficiently adds operational instructions in a logical order. Every sentence contributes necessary context for correct invocation, with no filler.

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

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

For a tool with no output schema, the description covers the return components (url, headers, filenameHeader) and the required follow-up workflow, which is enough to use it correctly. It still omits exact expiry duration and formal response shape, so it is strong but not fully exhaustive.

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 transactionId as the required UUID of the transaction to attach files to. The description adds only the general purpose of the parameter and no new syntax or format details, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: get a short-lived upload URL for attaching receipt/invoice files to a transaction. It also names accepted file types and the target entity, so an agent can identify exactly what this unique tool does.

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

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

It explicitly explains when to use it and the critical constraint that file bytes cannot be sent through MCP. It then gives the required alternative workflow: POST raw file contents to the returned URL with the returned headers and the filename header. It also states the client prerequisite, leaving no ambiguity.

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

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

No annotations are provided, so the description carries the full burden. It does disclose real behavior — nested categories via parentId and color inheritance from the parent — but says nothing about permissions, duplicate-name handling, the effect of type='internal', or what the call returns, which leaves meaningful gaps 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?

Three short sentences, front-loaded with the core action before the nesting detail and the usage note. Each sentence carries information, though the closing 'use when' sentence is close to filler given the already-clear purpose.

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

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

For a 5-parameter mutation tool with no annotations and no output schema, the description covers purpose and one notable behavior but omits return value, error/conflict behavior, and prerequisite permissions. Adequate but visibly incomplete.

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 description reinforces parentId/color inheritance but largely restates what the schema's own field descriptions already state, adding no new syntax or constraint detail.

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

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

States a specific verb and resource ('Create a new transaction category') that is unambiguous against catalog siblings such as create_tag and create_payee. It does not explicitly differentiate itself from those siblings, but the resource noun is distinct enough that no confusion arises.

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?

'Use when the user wants a new category to classify transactions' gives a clear triggering condition. There is no when-not guidance and no mention of alternatives (e.g. update_category for existing ones), which keeps it short of a 5.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses the plan/trial prerequisite, specific failure modes including exchange-rate issues and the 100% shared-account constraint, and the return shape. It could add more about duplicate-goal handling or side effects, but the core behavior is transparent.

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

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

The description is front-loaded with the create action, followed by failure conditions, prerequisite, and return shape in four efficient sentences. Every sentence contributes useful information with no filler.

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

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

For a 7-parameter creation tool with detailed schema coverage, the description supplies the remaining context an agent needs: feature availability, failure modes, account-sharing constraints, and return shape via the get_goals reference. No output schema exists, but the description adequately explains the result.

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

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

Schema description coverage is 100%, and the schema itself thoroughly documents parameters including the nested accounts funding rules. The description reinforces the funding model at a high level but does not add parameter-level meaning beyond what the schema already provides.

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

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

The description starts with a specific verb and resource: 'Create a savings goal', then specifies the target amount, optional date, and account-funding model. This clearly distinguishes it from sibling tools such as get_goals, update_goal, and delete_goal.

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 states a key prerequisite, 'Needs the Goals feature on the plan or an active trial', and lists failure conditions that help determine whether the call is viable. However, it does not explicitly name alternatives such as update_goal for modifying a goal or get_goals for listing goals.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the holding-existence prerequisite, but does not cover permissions, side effects on balances/holdings, duplicate handling, or auth requirements 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?

Three tightly packed sentences with no waste. Purpose is front-loaded, followed by the critical prerequisite and then the numeric formatting note.

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

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

For an 8-parameter mutation tool with no annotations and no output schema, the description covers the essential workflow and prerequisite. It is not exhaustive about side effects or return behavior, but the rich schema handles field-level 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 the schema already documents every parameter. The description's decimal-string guidance for quantity, price, and fees largely repeats schema details rather than adding new semantic constraints, so baseline 3 applies.

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

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

States a specific verb (Record), resource (investment transaction), and scope (in a portfolio), with common categories in parentheses. This differentiates it from generic transaction tools and portfolio cash transaction tools without needing to open the schema.

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

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

Gives a clear precondition and workflow: the security must already exist as a holding, and the agent should call search_securities to resolve a ticker to a securityId. It does not explicitly name when to use alternative tools such as create_portfolio_cash_transaction, but the context is strong.

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

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

No annotations are provided, so the description carries the full behavioral burden. It mentions that a Payee is returned, but says nothing about duplicate-name handling, side effects on existing payees/transactions, or permission requirements. For a mutation tool with zero annotation coverage this is a significant gap.

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

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

Three short sentences, front-loaded with the core action before the usage cue and return note. No filler, though 'Returns the created Payee' adds little concrete information given the absence of an output schema.

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

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

For a simple two-parameter create tool with a fully documented schema, the description covers purpose, when-to-use, and that something is returned. However, the return statement is vague with no output schema to fill in fields, and duplicate/permission behavior is unaddressed.

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

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

Schema description coverage is 100%, so both parameters (name, defaultCategoryId) are already fully documented in the schema. The description adds no syntax, format, or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb ('Create') and resource ('Payee'), and even clarifies the domain term as 'merchant/counterparty'. The create-vs-update/delete/get distinction from siblings is obvious from the verb alone, but no sibling is named explicitly, so it falls short of the top tier.

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 gives the triggering context: 'Use when the user wants to register a new merchant before linking transactions.' This is a clear condition for invocation. There is no when-not guidance (e.g., duplicates, or use update_payee instead), so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. It helpfully discloses the return ('Returns the created portfolio with its id') and downstream linkage, which is valuable since there is no output schema. However, it omits permission requirements, the duplicate-name failure behavior (only hinted at in the schema), and any reversibility/side-effect notes for this mutation.

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 tight sentences, front-loaded with the action, followed by usage context and the return/follow-up. Every sentence earns its place with no filler.

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

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

For a simple create operation with a fully documented schema and no output schema, the description supplies the missing return-value and follow-up context. It is nearly complete, losing only minor points for not covering failure modes or prerequisites of a mutation tool with no annotations.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including the enum values and the uniqueness constraint on name. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

Specific verb + resource ('Create a new investment portfolio') with clear scope ('for the user'). It distinguishes itself from the many other create_* siblings by naming the noun and the domain, though it does not explicitly contrast with near-neighbors like create_portfolio_cash_transaction or create_budget.

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

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

Gives concrete when-to-use context ('track a new brokerage account, retirement fund, or savings vehicle'), which maps cleanly onto the portfolioType enum. It stops short of naming when NOT to use it or naming an explicit alternative create tool, so it is clear context without 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?

With no annotations, the description carries the burden, and it does disclose a real behavioral trait: no bank transaction is created and no regular account is affected. It does not cover permissions needed, reversibility/undo path (e.g. delete_investment_transaction), or error behavior, which a mutation tool ideally should.

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

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

Two tight sentences with the primary behavior first and the routing rule second; every clause carries information and nothing is redundant.

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

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

For a 7-parameter mutation tool with no annotations and no output schema, the description covers purpose, scope, and sibling routing well. It omits any note on required permissions, validation failures, or how to reverse the entry, leaving a small gap.

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

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

Schema description coverage is 100%, so all seven parameters (including the enum on type and the isAdjustment flag) are already documented in the schema. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a precise verb and resource ('Record a direct cash deposit into or withdrawal from an investment portfolio') and scopes it negatively ('without touching any regular account'). An agent can distinguish it from the transfer siblings without opening the schema.

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

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

Explicitly names the alternatives (transfer_account_to_portfolio / transfer_portfolio_to_account) and the condition that selects them ('when the money moves to or from a tracked account'). This is exactly the when-to-use/when-not guidance the dimension rewards.

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?

With no annotations, the description carries the full behavioral burden. It discloses the required auth scope (`finance:write`) and installment-specific constraints (`maxOccurrences` and `dueDate`), which are valuable. But it omits other behavioral details such as idempotency, side effects (e.g., schedule creation), or what happens on duplicate input, leaving gaps.

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

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

The description is front-loaded with the core purpose, then flows logically through type guidance, installment requirements, amount format, and auth scope. Every sentence earns its place with no redundancy, and the size is appropriate for a 13-parameter tool.

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

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

Given 13 parameters, no output schema, and no annotations, the description covers purpose, type usage, key installment constraints, amount semantics, and auth scope. It could do more to explain side effects or return behavior, but for a create tool it is largely complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by explaining the use cases for each `type` enum value (SaaS/streaming, utilities, financed purchase) and clarifying that `expectedAmount` is a decimal in the subscription currency, going beyond the schema's brief descriptions.

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

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

The description states a specific verb (Create) and resource (subscription, recurring bill, or installment plan), and clearly distinguishes the three subtypes. The resource is distinct from siblings like create_transaction or create_budget.

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 choosing the `type` parameter (SaaS/streaming vs utilities vs financed purchase), which is helpful. However, it does not mention when to use this tool versus alternatives like `detect_subscription_candidates` or `link_transactions_to_subscription`, and offers no exclusions. Usage is implied rather than explicitly guided.

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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose the return value ('Returns the created tag with its ID'), but says nothing about the uniqueness constraint on name (only implied via schema), permissions, or failure behavior when a duplicate name is supplied.

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 short sentences, front-loaded with the action, then usage, then return behavior. No filler; each sentence adds a distinct piece of 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?

With no output schema, the description usefully states the return value, and the schema fully covers parameters. It is nearly complete for a simple create tool, missing only error/uniqueness behavior and permission expectations.

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 every parameter (name, color, icon, description) is documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a new tag') and clarifies what the tag is for ('assigned to transactions'). It does not explicitly distinguish itself from nearby siblings like create_category or update_tag, so it falls short of a 5.

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

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

Gives clear usage context: 'Use when the user wants to label or categorize transactions with a custom tag.' No when-not guidance or alternative (e.g., create_category for spend categorization) is offered, so it stops short of 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?

With no annotations, the description carries the full load and does well: it discloses that rule matching auto-adds transactions (a write side effect on other records), that AI mode scans a date range and produces suggestions, and what the call returns (tracker with ID, status, rule categories and tags). It stops short of stating permission requirements or what happens on validation failure.

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, front-loaded with the core action and its scope, then behavioral modes, then the return value. Every sentence adds information; only the return-value sentence is slightly redundant with an obvious creation result.

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 12-parameter creation tool with no output schema, the description covers scope, mode flags, follow-up tools, and the shape of the returned object. Minor gaps remain around failure modes and default behavior of rulesCleanup, which only the schema explains.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by surfacing cross-parameter dependencies (rulesEnabled needs categoryIds and/or tagIds; aiEnabled requires aiDescription and startDate) that are easy to miss when skim-reading 12 properties. It does not add format or unit details 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?

States a specific verb+resource ("Create a tracker") and immediately scopes it with the optional limit and date range. It also carves out the nearest ambiguous concept by declaring it does not create the period-based Budget plan, so an agent can separate it from budget-style tools without opening the schema.

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

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

Gives concrete routing: use rulesEnabled with categoryIds/tagIds for auto-add, use add_transactions_to_tracker to link existing transactions, and use list_tracker_suggestions to review AI results. The only missing piece is an explicit statement of when not to call it (e.g. vs update_tracker for existing trackers), which is largely self-evident from the name.

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

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

With no annotations, the description carries the full burden and does well: it discloses the permission requirement, the first-match-by-position categorization rule, the 'other' fallback, and the return payload. It omits what happens to already-existing transactions when a new line is inserted earlier in the order, which is a meaningful behavioral gap 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 tight sentences, front-loaded with the purpose, then matching semantics, then prerequisite, then return shape. Each sentence carries information; the only mild redundancy is restating child-category expansion that the schema also documents.

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 5-parameter create tool with no annotations and no output schema, the description covers purpose, prerequisite, matching behavior, and return value. The remaining gap is the side effect on existing transaction categorization, which an agent would otherwise have to guess.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains that a line's category set expands to children and that position determines which line captures a transaction (first match wins). That priority semantics for 'position' goes beyond the schema's '0-based order among the lines'.

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 ('Add a line to a tracker') and immediately defines what a line is (a named category set with an optional limit), which is the domain concept an agent needs to distinguish this from update_tracker_line or create_tracker. Sibling names aren't cited, but the add-vs-update distinction is unambiguous.

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

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

It gives a clear precondition ('Requires manage access to the tracker') and explains the matching semantics that motivate creating a line, but it never explicitly says when to use this instead of update_tracker_line or how it relates to add_transactions_to_tracker. Context is clear; exclusions are absent.

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 some behavioral context, such as paymentType defaulting to the account's default and originalAmount being informational only. But with no annotations, it does not fully disclose mutation side effects, permissions, idempotency, or what happens on failure, leaving meaningful gaps for a create operation.

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

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

The description is front-loaded with the core action and required parameters, then moves through optional and advanced scenarios. It is dense but appropriately sized for an 18-parameter creation tool, with little wasted 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?

Given the fully described schema, the description provides an adequate high-level summary of required fields, transfers, splits, original currency, and payment legs. It omits some advanced fields like isPlanned or destinationTransactionId, but the schema covers them, and no output schema needs explanation.

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 parameter documentation is already strong. The description summarizes key fields and conditional groups, but largely repeats or compresses what the schema more precisely explains; it does not add substantial 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 uses a specific verb and resource: 'Create a new transaction (income, expense, or transfer).' It clearly establishes scope and required fields, but does not explicitly differentiate this tool from siblings like update_transaction or split_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?

Usage is implied by 'Create a new transaction' and the conditional guidance for transfers, splits, original amounts, and payment legs. However, there is no explicit guidance on when to choose this tool versus alternatives such as update_transaction, split_transaction, or create_investment_transaction.

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?

With no annotations, the description carries the full burden and does so well: it discloses evaluation order (appended last), firing scope (newly synced/imported bank transactions only), exclusions (not transfers, not planned), the non-retroactive guarantee, and the required finance:write scope. These are exactly the behavioral facts an agent needs before writing.

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

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

Front-loaded with the core purpose, then scope, then the preview prerequisite and scope requirement in order of importance. Four compact sentences with minimal waste, though the action enumeration slightly overlaps 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 nested, multi-branch mutation tool with no annotations and no output schema, the description supplies the critical behavioral context (firing scope, ordering, exclusions, auth scope) that structured fields don't cover. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100% and the nested action/condition schemas are exhaustively documented, so the schema does the heavy lifting. The description's action list ('categorizes, tags, sets a payee, or edits the note') merely restates action types already in the schema, adding little beyond it; baseline 3 applies.

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

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

The description opens with a specific verb+resource ('Create a transaction automation rule') and enumerates the four effects the rule can have (categorizes, tags, sets a payee, edits the note). This clearly distinguishes it from siblings like update_transaction_automation and delete_transaction_automation without needing to open 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?

It explicitly routes the agent to preview_transaction_automation ('Preview the conditions ... first'), giving a concrete when-to-use instruction and a companion tool. It doesn't explicitly compare against update_transaction_automation for modifying an existing rule, so it falls short of full when/when-not coverage.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the finance:write scope and that transfer pairs are automatically included, but it does not explain what happens on failure, duplicate membership, or what the caller receives after creation.

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 four short sentences, front-loads the core action, and includes only useful constraints and an example. There is no redundant or wasted 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 mutation tool with no annotations and no output schema, the description covers the main call requirements: purpose, minimum transactions, automatic transfer inclusion, and auth scope. However, it does not state what is returned or how conflicting or duplicate transactions are handled, which leaves meaningful gaps.

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

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

Schema description coverage is 100%, so the schema already documents name, note, and transactionIds including min/max constraints. The description repeats the minimum of 2 transactions but adds no parameter-level meaning 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 states a specific verb and resource: 'Create a new transaction group that bundles related transactions together.' The split-bill example makes the grouping concept concrete. It is clearly distinct from create_transaction and add_transactions_to_group, though it does not explicitly name those siblings.

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

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

The description gives prerequisites such as 'Requires at least 2 transactions' and 'Requires finance:write scope,' but it does not say when to create a new group versus using add_transactions_to_group, update_transaction_group, or split_transaction. Usage is implied rather than explicitly routed.

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?

With no annotations, the description carries the full burden, and it discloses genuinely useful behaviors beyond the schema: platform-default fee auto-fill when platformId is supplied, the side effect of also creating an initial_investment event in the same operation, and the v1 SPV-only limitation. It stops short of covering auth/permission requirements or error/reversibility behavior, so it is strong but not complete.

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

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

Front-loaded with purpose, then ordered caveats (amount format, fee format, platform defaults, optional event, version limit). Each sentence carries distinct information with no filler.

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

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

For a 15-parameter creation tool with a nested initialInvestment object and no output schema, the description adequately covers format conventions, defaulting behavior, and the composite side effect. It does not address permissions or failure modes, but the core invocation-critical context is present.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real value: it clarifies that all monetary amounts are decimal strings in the deal currency, that fee percentages are fractions in [0,1] and emphatically NOT 8.5, and that omitted fee fields are auto-filled from platform defaults. This goes beyond what the schema descriptions convey.

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

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

States a specific verb+resource ("Create a venture deal") and immediately disambiguates with the parenthetical "(private/illiquid investment record)", distinguishing it from create_portfolio and create_investment_transaction. An agent can tell it apart from sibling creation tools without opening the schema.

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

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

Provides contextual constraints (platformId triggers fee auto-fill; initialInvestment triggers event creation; only SPV is supported in v1) but never states when to choose this over siblings like create_venture_event or create_portfolio. Usage is only implied by the resource scope.

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?

With no annotations, the description carries the full burden and does so well: it discloses auto-derived values (grossAmount from principal+entryFee, auto-computed carry), the side-effect difference between 'linked' (sum must equal lpNetAmount) and 'out_of_wallet' (no effect on bank balances or cash-flow charts), error behavior (clear ValidationError on invalid combos), and override escape hatches. This is materially beyond what the schema alone conveys.

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

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

Long but well-structured: the purpose and hard prerequisites are front-loaded, then bulleted per-type rules, then the cashFlowMode and carry semantics. Every section carries non-redundant information; the density is justified by the 11-parameter, 7-type surface.

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

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

Given no output schema and no annotations, the description covers prerequisites, per-type requirements, side effects, and error behavior thoroughly. The main omission is any hint of the response shape or whether the call is idempotent, but for a create tool with documented validation this is close to complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real conditional semantics the schema cannot express: which fields are required per event type, that grossAmount must NOT be passed for initial_investment, and that transactionIds must only accompany cashFlowMode='linked'. Only minor gaps remain (e.g. quantityPct usage is only lightly touched).

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

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

States a specific verb+resource ('Record an event on a venture deal'), which cleanly separates it from create_venture_deal, create_venture_platform, and update_venture_event. It doesn't explicitly name a sibling to disambiguate against, but the resource boundary is unambiguous from the name and opening sentence.

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

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

Gives concrete preconditions ('deal must already have an initial_investment before any other event type can be created') and a date-ordering constraint, plus per-type validity rules. It stops short of naming alternatives (e.g. when to prefer update_venture_event over creating a new event), so it lacks explicit exclusion guidance.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the useful return behavior (the created platform's id, for use with create_venture_deal), but says nothing about permissions, whether a duplicate name fails, or any side effects of creating the record.

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 tight sentences, correctly front-loaded with purpose before the unit convention and the return-value note. The middle sentence duplicates guidance already in the schema, slightly diluting conciseness.

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-param creation tool with full schema coverage but no annotations and no output schema, the description supplies the two missing pieces an agent needs: the unit convention trap and what the call returns. Remaining gaps (auth requirements, uniqueness failure behavior) are modest.

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 fields are already documented with units and defaults, making 3 the baseline. The description restates the decimal-fraction convention already present on each fee parameter ('NOT 8.5') and adds no new per-parameter semantics.

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

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

Opens with a specific verb+resource ('Create a venture investment platform') and grounds it with concrete examples (AngelList, syndicate, fund manager). It also states why the entity exists (to auto-apply default fees on new deals), which cleanly separates it from create_venture_deal and create_portfolio.

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

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

Gives a clear when-to-use rationale — creating a platform to carry default fee settings into future deals — and names the downstream tool (create_venture_deal) that consumes its output. It does not state any exclusions or when-not-to-use conditions, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full burden and does so well: it discloses permanence ('permanently'), the destructive nature, two distinct failure modes (linked transactions without a replacement, parent category with subcategories), and a required reassignment step. It stops short of describing permission requirements or what the response returns, keeping it from a 5.

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

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

Three sentences, each earning its place: the action, the conditional prerequisite with its failure consequence, and the hard constraint plus confirmation guardrail. The core action is front-loaded in the first clause.

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

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

No output schema or annotations exist, so the description must stand alone, and it covers action, prerequisites, failure modes, and a safety guardrail for a 2-parameter mutation. Minor gaps remain around permissions and side effects on the orphaned data once reassigned, but nothing needed 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 both parameters are already documented, giving a baseline of 3. The description goes beyond that by tying replaceWithCategoryId to its triggering condition and the consequence of omitting it (the call fails), which is semantic value the schema's terse 'Required when the category has transactions' only partially conveys.

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

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

States a specific verb and resource ('Permanently delete a category by ID') with the scope qualifier 'permanently'. It is clearly distinguishable from sibling deletions like delete_budget, delete_tag, or delete_transaction, all of which target different resources.

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

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

Gives an explicit precondition ('Only call when the user explicitly confirms deletion') and the exact condition under which the optional parameter becomes mandatory ('if the category has linked transactions you must supply replaceWithCategoryId'). It also names a hard when-not case: a parent category with subcategories cannot be deleted. No sibling tool offers category deletion, so no alternative needs naming.

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

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

No annotations are provided, so the description carries the full burden: it discloses irreversibility ("Permanently"), the side effect on account shares, an explicit non-effect on accounts/balances, and the return shape {"success": true}. What it omits is whether the deletion requires ownership/admin rights or fails when shares still exist — minor but real gaps for an irreversible mutation.

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 short sentences, front-loaded with the destructive verb, then consequences, then the alternative. "Free its account shares" is slightly opaque phrasing, but every sentence earns its place and nothing is padding.

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

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

For a one-parameter irreversible delete with no output schema and no annotations, the description covers purpose, side effects, alternative, and return value — enough to call it correctly. It stops short of error conditions or permission requirements, which is the only meaningful remaining gap.

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

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

There is a single required goalId parameter with 100% schema description coverage, so the schema already fully documents it. The description adds no format, sourcing, or validation nuance beyond that, which is the baseline expectation when the schema does the work.

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

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

States a specific verb and resource ("Permanently delete a savings goal") with the scope of the deletion spelled out. It clearly distinguishes itself from the sibling update_goal, which is named explicitly, so an agent can route without opening either schema.

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

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

Names the alternative ("Prefer update_goal with status archived to keep it") and the condition that selects it, which is exactly the fork an agent faces with a delete tool. It also bounds the blast radius up front by saying accounts and balances are not touched.

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?

With no annotations, the description carries the full burden and does so well: it declares the operation permanent and irreversible, warns to confirm first, and discloses the non-obvious side effect that the holding and portfolio cash balance are recalculated. It omits auth/permission requirements and error behavior, so it falls short of a 5.

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

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

Four short sentences, front-loaded with the action and its consequence, then the irreversibility warning, then the ID source. No sentence is filler and each adds a distinct fact.

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-param destructive tool with no annotations and no output schema, the description covers the essentials: permanence, side effects, and ID provenance. It is nearly complete, though it could note permission requirements or what happens to the linked portfolio/holding records.

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 is fully documented with a UUID pattern and source hint. The description's mention of obtaining transactionId from get_investment_transactions merely duplicates the schema, so it adds no meaning beyond structured data — baseline 3.

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

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

States a specific verb ('delete') and resource ('investment transaction'), and the qualifier 'investment' distinguishes it from the sibling delete_transaction. An agent can identify exactly what is being removed without opening the schema.

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

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

Gives clear pre-call guidance ('confirm with the user before calling') and tells the agent where to obtain the ID ('from get_investment_transactions'). However, it never explicitly contrasts this with delete_transaction or states when an agent should prefer an alternative such as update_investment_transaction.

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?

With no annotations, the description carries the full burden and does so well: it declares irreversibility, the exact side effect on linked records (categoryId retained, payeeId nulled), and the required finance:delete scope. It stops short of describing the response or failure behavior (e.g., deleting a missing payee).

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 short sentences, zero waste, with the destructive side effect and the caution placed before the scope requirement. 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 one-parameter destructive tool with no annotations and no output schema, the description covers the critical unknowns: irreversibility, referential side effects, and authorization scope. Only the return/error behavior is left unstated, which is a minor gap.

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

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

Single id parameter with 100% schema description coverage; the schema already says 'Payee id to delete.' The description adds nothing parameter-specific, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete a Payee') and immediately qualifies the scope with what happens to linked transactions. An agent can distinguish it from create_payee, update_payee, and merge_payees 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?

'Use cautiously — this is irreversible' sets a usage caution, but it never names an alternative such as merge_payees for the common case of consolidating duplicate payees, nor states when-not-to-use. Usage is implied rather than routed.

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?

With no annotations, the description carries full burden and does well: it discloses irreversibility, the cascade destruction of holdings/transactions/balances under force, the blocking condition, and a confirmation requirement. It omits permission/auth requirements and rate limits, which is the remaining gap.

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

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

Three tightly packed sentences: core action first, then the flag semantics, then the safety warning and ID source. No filler 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 destructive tool with no annotations and no output schema, the definition covers action, cascading effects, blocking condition, and irreversibility well. Missing only ancillary details like auth requirements or the effect on linked venture/transfer records.

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 description's explanation of force largely mirrors the schema's own description, and 'Obtain portfolioId from get_portfolios' repeats the schema note, so it adds little meaning beyond the structured fields.

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

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

States a specific verb and resource ('Permanently delete a portfolio') and immediately qualifies scope with the cascade behavior tied to the force flag. An agent can distinguish this from the sibling create_portfolio, update_portfolio, and get_portfolios 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?

Clearly explains the force/no-force decision ('Without force, deletion is blocked when the portfolio has any data') and prescribes a user confirmation step. It does not name a sibling alternative (e.g., a soft-archive path) for cases where deletion is undesirable, so it stops short of explicit 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?

With no annotations, the description carries the burden and does disclose key behavior: the operation is DESTRUCTIVE and the split amount returns to the primary category. It also names a failure condition when refunds target the split. It stops short of mentioning auth requirements or reversibility.

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 compact sentences that front-load the action and identifier, then layer the destructive side effect and failure condition. No filler text.

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

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

For a simple one-parameter deletion tool with no output schema, the definition covers purpose, side effect, and failure condition. Minor gaps remain (auth needs, relationship to the parent transaction), but nothing critical to correct invocation is missing.

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

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

Schema description coverage is 100%, so the single parameter is already fully documented as 'UUID of the split to delete'. The description's '(UUID string)' merely restates that format and adds no new semantics. Baseline 3 applies.

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

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

States a specific verb (delete) and resource (split) with an explicit scope ('a single split from a transaction'). It clearly distinguishes itself from siblings like split_transaction (creates splits) and delete_transaction (removes the whole transaction), so an agent can identify it without opening the schema.

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

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

The description gives an implicit when-not condition ('Fails if the split has refunds targeting it') but does not name alternatives such as split_transaction or delete_transaction or state prerequisites. Usage is only implied, not spelled out.

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?

With no annotations, the description carries the full behavioral burden and does well: it discloses irreversibility ('cannot be undone'), a cascade side effect ('Linked transaction associations are also removed'), and the required auth scope ('finance:delete scope'). It stops short of clarifying whether linked transactions themselves are deleted or merely unlinked, so 'associations' remains ambiguous.

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 short sentences, front-loaded with the action and its permanence, then the cascade effect, then the permission requirement. Every sentence earns its place with no filler.

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

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

For a one-parameter destructive tool with no annotations and no output schema, the description supplies the key context an agent needs before invoking: irreversibility, cascading deletion, and required scope. The only real gap is the ambiguity around what happens to the linked transactions themselves.

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

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

There is a single parameter with 100% schema description coverage ('UUID of the subscription to delete'), so the schema already carries the semantics. The description adds no format or sourcing detail (e.g., where to obtain the UUID), 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 first sentence gives a specific verb ('Permanently delete') and resource ('a subscription or recurring bill'), immediately distinguishing it from neighboring delete_* tools that target other resources. An agent can select this tool without opening the schema.

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

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

The word 'Permanently' implicitly contrasts with the sibling toggle_subscription_active, but the description never names an alternative or states when deletion is preferable to deactivation/archiving. Usage is only implied.

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

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

With no annotations, the description carries the full burden and does well: it discloses irreversibility ('permanently'), the cascading side effect ('unlinked from all transactions'), and the confirmation requirement. It omits permission/auth requirements and error behavior, keeping it out of 5 territory.

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

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

Two tight sentences, front-loaded with the destructive nature before the confirmation gate. Every clause earns its place; nothing is redundant.

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

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

For a single-parameter delete with no output schema, the description supplies the key facts an agent needs: permanence, unlinking side effect, and the confirmation precondition. Auth requirements and failure modes are the only notable omissions.

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

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

Only one parameter (id) and schema description coverage is 100%, with a UUID format and pattern fully documented in the schema. The description's 'by ID' adds no syntax or constraint information beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Permanently delete a tag by ID'), and 'permanently' usefully distinguishes it from softer alternatives like archive/update operations in the sibling set. It does not explicitly name a sibling to route against, so it stops short of a 5.

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

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

Gives an explicit gating precondition: 'Only call when the user explicitly confirms deletion.' That is clear when-to-use guidance, though it does not contrast with alternatives such as update_tag or archive-style operations, nor describe what to do if confirmation is absent.

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?

With no annotations, the description carries the full burden, and it does disclose the key traits: irreversibility, cascading removal of transaction links, and the return payload. It says nothing about required permissions or any other side effects (e.g. impact on tracker lines or suggestions), so it is partial rather than complete.

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 short sentences, front-loaded with the core action and immediately followed by the irreversible warning and return shape. Nothing is padded.

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

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

No output schema exists, but the description supplies the success response shape, plus scope and irreversibility. Only permission requirements and collateral effects on adjacent resources are unstated.

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 is fully specified with type, format, pattern and description. The description adds no parameter-level detail, so the 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?

Specific verb (delete) plus resource (tracker) and scope (all its transaction links). The adverb 'Permanently' implicitly distinguishes it from archive_tracker, but no sibling is named, so an agent must infer the archive-vs-delete choice itself.

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

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

There is no when-to-use or when-not-to-use guidance. For an irreversible destructive tool with archive_tracker available as a non-destructive alternative, the absence of any routing hint is a meaningful 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?

With no annotations the description carries the full burden and does so well: it discloses irreversibility ('Permanently delete'), the non-obvious side effect (transactions survive and their spending is reassigned to the next matching line or 'other'), the required permission level, and the return value. This is exactly the destructive-operation context 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?

Three short sentences, zero filler, and the destructive nature is front-loaded before the side-effect and permission details. 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 destructive mutation with no output schema, the description covers permanence, cascade behavior, authorization, and the response shape ({ success: true }), leaving no gap an agent would need to guess at before calling.

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

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

Schema description coverage is 100% and both parameters (lineId, trackerId) are documented in the schema, so the description adds no syntax or format detail beyond it. Baseline 3 for a fully-covered 2-parameter schema.

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

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

States a specific verb plus resource ('Permanently delete a line from a tracker'), which cleanly separates it from delete_tracker, delete_transaction and update_tracker_line in a crowded sibling list. An agent can identify the operation without opening the schema.

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

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

The description implies when it applies ('Permanently delete a line') and gives a precondition ('Requires manage access to the tracker'), but never names an alternative or a when-not condition (e.g. archive_tracker, remove_transactions_from_tracker, update_tracker_line). Usage is inferable but not routed.

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?

With no annotations provided, the description carries the full burden and does meaningful work: it discloses irreversibility ('cannot be undone') and the non-obvious cascade that both legs of a transfer are removed. It stops short of stating permission requirements or what happens to linked items like splits, tags, or refund links.

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

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

Two short sentences, zero filler, with the destructive warning front-loaded immediately after the purpose. Every clause earns its place.

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

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

For a one-parameter destructive tool with no output schema and no annotations, the key risks (permanence, transfer cascade) are covered. Remaining gaps are secondary details like auth needs and treatment of linked records.

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 'id' param is fully documented as a UUID with a pattern, so the schema already does the work. The description adds only 'by ID', which is baseline-level reinforcement.

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

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

States a specific verb+resource ('Permanently delete a transaction') and the identifier used to target it. It is distinguishable from the many other delete_* siblings by naming the resource, though it never explicitly contrasts itself with delete_investment_transaction or the archive_* 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?

No guidance on when to use this versus alternatives such as archive_account, delete_transaction_group, or delete_split, nor any prerequisites or preconditions. The agent is left to infer that this is the tool for removing a single transaction.

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?

With no annotations, the description carries the full burden and does so: it discloses irreversibility ('This cannot be undone'), the side effect on already-changed transactions ('keep their values'), the required auth scope (finance:delete), and the return shape. Nothing critical is left undisclosed for a destructive operation.

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

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

Five short sentences, each carrying distinct information (destructive semantics, side effect, confirmation requirement, alternative, return value, scope) and front-loaded with the core action. 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?

For a destructive single-parameter tool with no annotations and no output schema, the description supplies everything an agent needs: irreversibility, confirmation requirement, alternative path, required scope, and the return value.

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

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

There is a single parameter whose schema description coverage is 100%, so the schema already documents 'id' as the UUID of the automation. The description adds no syntax or format detail beyond that, making the baseline 3 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?

States a specific verb (permanently delete) and precise resource (transaction automation rule), and distinguishes itself from sibling delete tools like delete_transaction_group by naming the exact entity. An agent can identify the operation without opening the schema.

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

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

Explicitly states when to call it (only on explicit user confirmation of deletion) and provides a named alternative for the adjacent case (set isEnabled to false via update_transaction_automation to stop a rule temporarily). This is a textbook when/when-not/alternative 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?

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses irreversibility ('cannot be undone'), the exact scope of destruction (group only, not transactions), and the required permission scope (finance:delete). This is exactly the context an agent needs before invoking a destructive mutation.

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 tight sentences, front-loaded with the action, then the critical scope caveat, then the reversibility warning and permission requirement. Every sentence earns its place with no redundancy.

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

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

For a single-parameter destructive tool with no annotations and no output schema, the description covers everything an agent needs: what is destroyed, what is preserved, irreversibility, and auth scope. Nothing material 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% – the single 'id' parameter is fully documented as 'ID of the transaction group to delete' with format and pattern constraints. The description adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Permanently delete a transaction group') and immediately clarifies scope by distinguishing it from deleting the underlying transactions. This sharply differentiates it from the sibling delete_transaction and remove_transactions_from_group.

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 use case clear (destructive group removal) and implicitly routes away from delete_transaction, but it doesn't name the alternative tool or explicitly state when to prefer removing transactions from a group versus deleting the group itself.

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?

With no annotations, the description carries the full burden and does so well: it discloses destruction scope (cascade-deletes events and event-link rows), a non-obvious side effect (linked bank transactions remain intact and are restored to their original state), and reversibility (soft-delete vs hard-delete via force). These are exactly the traits an agent needs before invoking a destructive operation.

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

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

Front-loads the core action in the first sentence, then layers cascade scope, side effects, and confirmation guidance in a logical order. Slightly redundant with the schema on the force behavior, but every sentence is otherwise informative.

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

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

No output schema or annotations exist, so the description must stand alone, and it covers destruction scope, side effects, and reversibility adequately for correct invocation. Permission/auth requirements and error conditions are unaddressed, which is the only meaningful remaining gap.

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

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

Schema coverage is 100% and the schema already documents both parameters, including the force default and dealId provenance ('from list_venture_deals'). The description restates the force semantics rather than adding meaning beyond them, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete a venture deal') and immediately scopes it with cascade behavior. An agent can distinguish it from sibling deletes like delete_venture_event or delete_venture_platform because the target resource is named precisely and the cascade relationship to those siblings is spelled out.

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

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

Provides clear context including a precondition ('Confirm with the user before calling') and explains the force parameter's selection semantics. It does not name alternatives or when-not-to-use conditions, but there is no obvious competing sibling that needs 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?

With no annotations, the description carries the full behavioral burden and does so well: it discloses that linked bank transactions are unlinked first and their original state restored, that setting deleteLinkedTransactions=true permanently removes bank transaction rows, and that the initial_investment has a dependency constraint. It also adds a safety instruction to confirm with 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 front-loaded with the core action, then each following sentence adds distinct operational value: side effects, dependency, parameter semantics, and a safety check. 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 delete tool with no annotations and no output schema, the description covers the essential context: what is deleted, what happens to linked transactions, dependency restrictions, the destructive option, and a confirmation requirement. No critical behavioral gap remains 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?

Schema coverage is 100%, establishing a baseline of 3. The description goes beyond the schema by explaining the user-explicit-ask condition for deleteLinkedTransactions and the special constraint on the initial_investment event, but it adds no further semantic detail for the eventId 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 states a specific verb and resource ('Delete a venture event') and adds constraints that clarify the scope. However, it does not explicitly distinguish this tool from sibling delete tools such as delete_venture_deal or delete_venture_platform, so it falls short of full sibling differentiation.

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

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

The description gives strong when/when-not guidance: deleteLinkedTransactions only 'when the user explicitly asks', initial_investment cannot be deleted while other events exist, and it says to confirm before calling. It does not name alternative tools (e.g., update_venture_event or delete_venture_deal) to route the agent, so it stops short of a full 5.

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

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

With no annotations to lean on, the description carries the full load and does so well: it discloses the effect on related records (references have platformId cleared, deals preserved), the hard-vs-soft delete distinction for force, and the requirement to confirm with the user. This is exactly the behavioral context an agent needs before mutating user data.

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

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

Three tight sentences, front-loaded with the core action and side effects; the confirmation warning comes last as an operative caveat. 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 destructive mutation tool with no annotations and no output schema, this covers side effects, the force decision, and user confirmation. It stops short of stating whether a hard delete is irreversible or what permissions are required, which would fully close the gap.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning beyond the schema by explaining the consequence of force (hard delete vs default soft delete) and the preservation of referencing deals.

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

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

Opens with a specific verb+resource ('Delete a venture platform') and is clearly distinguishable from siblings like delete_venture_deal and delete_venture_event. An agent knows exactly what this targets.

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

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

Provides a confirmation instruction ('Confirm with the user before calling') and implies the force flag's decision point, but never states when to choose this over archive-style alternatives or when to prefer soft vs hard delete beyond the parameter's own semantics.

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?

With no annotations, the description carries the full burden and does so well: it warns the operation 'can be slow on large transaction histories,' discloses a 1-hour result cache, tells the agent to read isFromCache for freshness, and states the required finance:write scope and its side effect (writes candidate records). This is exactly the behavioral context an agent needs before invoking a potentially expensive, mutating scan.

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 tightly packed sentences, front-loaded with the core action, then performance, caching, and scope. Every sentence adds a distinct operational fact 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?

No output schema exists, yet the description flags the isFromCache response field, and with no parameters and no annotations the remaining burden (performance, caching, auth, side effects) is fully covered. It could go slightly further on how results relate to the existing candidate list, but it is otherwise complete.

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

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

The tool takes zero parameters, so the schema is empty and there is nothing to document. Baseline for a parameterless tool is 4; the description correctly adds no parameter noise.

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

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

States a specific verb+resource: 'Scan the past 12 months of transactions to detect recurring payment patterns and generate subscription candidates.' This clearly distinguishes a detection/generation operation from the read-only sibling list_subscription_candidates. It does not explicitly name that sibling, so it falls just short of the top score.

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

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

The caching note implies usage ('subsequent calls within the cooldown return cached candidates'), which tells the agent when calling again is worthwhile, but there is no explicit when-to-use versus list_subscription_candidates or create_subscription, and no stated prerequisites beyond the scope requirement.

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?

No annotations are provided, so the description carries the burden well: it discloses the non-destructive side effect on underlying transactions, the pending-only precondition, and the required auth scope. This is solid behavioral context for a mutation tool, though it lacks details on return value or reversibility.

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 short sentences, front-loaded with the action and effect, followed by constraints and scopes. No wasted words.

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

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

Given no output schema and one simple parameter, the description provides sufficient context: purpose, side effects, precondition, and required scope. Only minor gaps such as error behavior or return format remain, which are acceptable here.

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 fully documents candidateId. The description adds no parameter-level detail, 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?

States a specific verb (dismiss) and resource (pending subscription candidate) with the observable effect on the candidate list. Distinguishes from sibling tools like delete_subscription (permanent) and detect_subscription_candidates.

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

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

Clearly implies usage for pending candidates only ('Only pending candidates can be dismissed') and notes non-destructive relationship to transactions. Does not explicitly name alternatives (e.g., delete_subscription), but the constraint provides good context.

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

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

With no annotations, the description carries the full burden; it implies a read-only listing operation and usefully enumerates the returned fields (balances in original and base currency, credit limit), which no output schema provides. However it says nothing about authentication needs, pagination, ordering, or whether excluded-from-stats accounts appear by default, so behavioral coverage is partial.

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

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

Two tight sentences: the first front-loads the action and scope, the second enumerates return contents. Every clause earns its place with no filler.

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

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

For a parameterless-required read tool with no annotations and no output schema, the description adequately covers purpose and return shape, and the schema covers both parameters. It stops short of noting that no filtering is applied by default or how results are ordered, but nothing essential to invocation is missing.

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

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

Schema description coverage is 100%, with both the 'type' filter and 'includeExcludedFromStats' flag documented in the schema itself, so the baseline of 3 applies. The description adds nothing about either parameter, so it neither compensates nor detracts.

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

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

The description names a specific verb and resource ('List all user accounts with current balances') and enumerates what is returned, so the agent knows exactly what this tool fetches. It is clearly distinct from write siblings like adjust_account_balance or archive_account, though it never explicitly contrasts itself with the nearest read siblings such as get_portfolio_balances or get_user_profile.

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

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

There is no statement of when to reach for this tool versus alternatives, no prerequisites, and no exclusions. The description only asserts that it lists all accounts, leaving the agent to infer context of use from the name alone.

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

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

No annotations are provided, so the description carries the full burden. 'Get' implies a safe read, but the description says nothing about granularity of the returned series, pagination, result caps, or auth requirements. It usefully discloses the per-account vs. aggregate branching, but for a no-annotation tool that is only partial coverage.

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

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

Three short sentences with the core purpose front-loaded and no filler. The branching clause is placed logically after the purpose statement, though it slightly restates what the schema's accountId description already says.

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

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

For a 3-parameter, zero-required, read-only query with a fully documented schema and no output schema, the description covers what is queried and the aggregate-vs-single behavior. The main omission is any hint about the shape or granularity of the returned history, which matters slightly without an output schema.

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

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

Schema description coverage is 100% — startDate, endDate and accountId all carry their own descriptions including defaults and the 'omit for combined' rule. The description restates the accountId semantics but adds no new syntax, format, or constraint information, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get account balance over time') and clarifies the branching behavior: per-account history when accountId is supplied, combined balance otherwise. It is clear on its own, but it never names the adjacent tools (get_cash_flow, get_portfolio_balances) that an agent might confuse it with.

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 conditional usage for its own parameter ('If accountId is provided... Otherwise...'), which is genuinely helpful. However it offers no guidance on when to prefer this tool over get_cash_flow or get_portfolio_balances, so routing among balance-related siblings is left to inference.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses the return shape (period-by-period breakdown, totals, savings rate), which is real value given there is no output schema. However, it says nothing about read-only safety, permissions, or rate limits for what is evidently a read query.

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

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

Two tight sentences with the resource and scope front-loaded and zero filler. Could be slightly tighter by folding the parenthetical enum restatement, but nothing is wasted.

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

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

With no annotations and no output schema, the description compensates by describing the return contents (breakdown, totals, savings rate), which is the key missing structured info. It is complete enough to call the tool correctly, with the usage-guidance gap the main shortfall.

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 five parameters are already documented. The description restates the granularity options (monthly/biweekly/weekly) which are already in the enum, and adds no syntax or semantics beyond the schema. Baseline 3 applies.

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

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

Clear verb+resource: 'Get income, expenses, and net cash flow for a period' with configurable granularity. Distinguishes itself by aggregating income + expenses + net flow, but does not name any sibling such as get_expenses_for_period or get_spending_by_categories, so an agent must infer the boundary.

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

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

The description implies a per-period reporting use case but gives no explicit when-to-use, when-not-to-use, or alternatives. With siblings like get_expenses_for_period and get_spending_by_categories in the same family, the agent gets no 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the return fields (id, name, color, icon, type, parent id) and the hierarchical parent relationship, but says nothing about ordering, pagination, completeness, or whether it includes archived categories.

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 compact sentences with no filler. The primary purpose is front-loaded and the return-field detail follows it, so every sentence earns its place.

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

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

With no output schema and no annotations, the description must carry the return contract itself, and it does enumerate the fields. It is close to complete for a trivial zero-param list tool; only ordering/archived-item behavior is left unstated.

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

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

The tool takes zero parameters, so there is no parameter syntax to document; the baseline for a 0-param tool is 4. The description appropriately uses its space to describe output rather than nonexistent inputs.

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

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

States a specific verb+resource ('List all transaction categories') and enumerates the fields returned, so the agent knows exactly what it produces. It does not explicitly differentiate itself from siblings like get_spending_by_categories or get_tags, but the resource is unambiguous.

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

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

There is no when-to-use guidance, no exclusions, and no named alternative. 'List all' implies no filtering, but the description never tells the agent when to prefer this over create_category/update_category/get_spending_by_categories or how to get a single category.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose the return shape ('a single total number'), which is real value given there is no output schema, but it says nothing about whether transfers/refunds are included, permission requirements, or any rate limits. Adequate but thin for a zero-annotation 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 tight sentences, zero filler, front-loaded with what it returns before the usage hint. Every clause earns its place.

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

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

For a 4-param read tool with no output schema and no annotations, the description covers purpose, return type, and use case, while the schema covers all parameter semantics. The remaining gap is edge-case behavior (what is included or excluded in the total), which an agent would plausibly want.

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% – defaults for startDate/endDate, the account filter, and the category-exclusion list are all documented in the schema. The description adds no syntax, format, or interpretation beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource (get total expense amount) plus the scope (a date range) and the return shape (a single total number). The 'single total number' framing cleanly separates it from the aggregate-breakdown siblings like get_spending_by_categories or get_cash_flow.

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 frames the use case ('quick how much did I spend queries instead of summing transactions manually'), which tells the agent when to reach for it over search_transactions. It does not name any sibling tool as an alternative or state when this tool is the wrong choice, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden and largely meets it: it discloses computation semantics (fixedAmount vs sharePercent ordering, credit-limit floor), the status enumeration, the reachedHoldDays stickiness rule, achievedAt clearing conditions, and when progress is null. It does not discuss authorization, caching, or rate limits, so the behavioral picture of the read itself is incomplete.

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 basic purpose is front-loaded in the first sentence, but the remaining content is a single dense run-on covering currency conversion, allocation rules, and nine status values with no bullet structure or paragraph breaks. Every sentence carries information, but the wall of text makes it hard for an agent 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?

There is no output schema and no annotations, so the description must explain the return shape, and it does so exhaustively: per-goal currency, target fields, backing accounts, the full progress object, all status values, and null-progress conditions. Nothing an agent needs to interpret the result is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there are no parameter semantics to add or omit. The description does not need to explain inputs because none exist.

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

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

The first sentence states a specific verb and resource ('List savings goals') plus scope ('active, paused, archived') and ordering, and the final sentence explicitly excludes the Budget plan's envelope line goals, which is the distinguishing feature from sibling get_trackers. An agent can select this tool 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?

It gives clear context (read/list savings goals) and an explicit exclusion ('Not the envelope line goals of the Budget plan'), but never states when to prefer it over siblings such as get_trackers or when a goal list is inappropriate. The routing is inferable rather than spelled out.

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?

No annotations are provided, so the description carries the burden; it discloses the default window (20 most recent across all portfolios) and the returned fields, which is useful. However, it says nothing about pagination interaction with defaults, ordering guarantees, or any permission expectations for a financial data read.

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 tight sentences that front-load what the tool returns before the sibling differentiation and default scope. The category enumeration is somewhat listy but earns its place by hinting at filterable values.

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

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

For a read-only list tool with a fully documented schema but no output schema, the description usefully enumerates the returned fields (amount, quantity, price, fees, date, category, embedded security) and the default scope. Only pagination/ordering semantics are left implicit.

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 every parameter is already documented in the schema; the description only reiterates the default limit of 20 and lists the category values already present as an enum. No additional syntax, format, or interaction guidance beyond what the schema provides.

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

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

States a specific verb+resource ('Investment transaction history') and enumerates the categories it covers, plus explicitly distinguishes itself from search_transactions which handles non-investment spending. An agent can unambiguously tell this apart from its closest sibling.

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

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

Names the alternative tool (search_transactions) and the condition that selects it, and states the default behavior (20 most recent across all portfolios). It lacks explicit 'when not to use' guidance for the other investment siblings like get_portfolio_holdings or list_portfolio_transfers, but the core routing is clear.

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

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

No annotations are provided, so the description carries the full disclosure burden. It does reveal return content (aliases, computed stats), which is useful, but it never states that this is a read-only operation or what happens on an unknown id. Adequate but with a real gap for an annotation-free 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 short sentences, zero filler, with the primary action front-loaded and the usage condition second. Every clause earns its place.

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

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

For a single-parameter read tool with no output schema, the description supplies the essentials: what it returns (aliases, stats) and when to reach for it. Only the absence of read-only confirmation and not-found behavior keeps it from being fully complete.

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

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

Schema coverage is 100% and the sole parameter is documented as 'Payee id.' The description adds only that this id refers to a merchant/payee lookup, which is marginal. Baseline 3 applies when the schema does 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?

States a specific verb and resource ('Fetch a single Payee') and adds the payload detail ('with aliases and computed stats'). The word 'single' implicitly separates it from the sibling list tool get_payees, though it never names that sibling explicitly, so it stops just short of full differentiation.

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

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

Gives a concrete trigger condition: use it when the user references a merchant by id and wants the full record. That is clear usage context, but it names no alternatives (e.g. get_payees for listing) and states no exclusions or failure cases.

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

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

With no annotations, the description carries the disclosure burden. It partially meets it by naming the return shape (id, name, defaultCategoryId, aggregated stats) and the read-only listing semantics implied by 'List'. It stops short of stating pagination, result limits, or sort order — material omissions for a list endpoint with no output schema.

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 no filler, front-loaded with the verb and resource, then the filter, then the return shape in a parenthetical. The return enumeration is slightly dense but each clause carries distinct 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 one-parameter list tool with no output schema and no annotations, the description supplies the purpose, the filter semantics, and the return fields, which is the bulk of what an agent needs. The remaining gaps are pagination/limits and explicit sibling routing, both minor but non-trivial.

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 single 'q' parameter is already documented in-schema as a substring filter on the normalized payee name. The description adds only the word 'optional' beyond the schema. Baseline 3 applies when the schema does 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?

States a specific verb and resource ('List Payees') and disambiguates the domain term by defining a payee as 'merchants/counterparties for the user'. It also enumerates the returned fields, so an agent knows this is a bulk-listing read. It does not explicitly contrast with the sibling 'get_payee' (singular), leaving that differentiation to inference.

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 notes the filter is 'optional' and applied as a 'substring query', which implies the no-arg path lists everything. However, there is no explicit when-to-use guidance and no mention of the sibling tools an agent might reach for instead (get_payee for one payee, merge_payees for consolidation). Usage is implied rather than stated.

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

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

No annotations are provided, so the description carries the disclosure burden. It does useful work by describing the response shape (totalCash, availableCash, and converted ref* fields), but says nothing about read-only nature, permissions, or freshness of the balance data.

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

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

Three short sentences, front-loaded with the core definition before the response detail and the use-case hint. No filler, though the third sentence is more of a nice-to-have than essential 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?

With no output schema, the description usefully explains what each entry contains and the base-currency conversion, covering the main return-value gap. For a simple read tool it is nearly complete; only permissions and read-only confirmation are absent.

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

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

Schema coverage is 100%: both portfolioId and currencyCode are documented in the schema, including the 'omit to return all currencies' behavior. The description adds no parameter-level detail beyond what the schema already provides, 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?

States a specific verb (get) and resource (cash balances in a portfolio), plus the scope (broken down per currency). An agent can tell this apart from holdings/summary tools in spirit, but the description never names the closest siblings (get_portfolio_holdings, get_portfolio_summary), so differentiation is implicit rather than explicit.

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

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

The closing line gives an implied use case ('how much cash do I have to invest'), which signals when to reach for it. There is no explicit when-not guidance and no named alternative for portfolio value or holdings questions, so routing still requires 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?

No annotations are provided, so the description carries the full burden. It does usefully disclose that values are 'dynamically calculated' and that each holding embeds a security object, which sets expectations for the response shape. However, it says nothing about authorization requirements, pagination behavior for large portfolios, or how the historical date interacts with the required portfolioId, leaving real gaps for a read tool with zero annotation coverage.

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

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

Three tight sentences with the core purpose and returned fields front-loaded, followed by supporting detail and the filter hint. Every sentence contributes; no filler or restatement of the tool name.

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

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

With no output schema, the description does the work of describing return values, covering computed fields, the embedded security, and the securityId filter. For a straightforward read tool this is nearly complete, though a note on result size or pagination would close the remaining gap.

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

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

Schema description coverage is 100%, so all three parameters are already documented (date defaults to latest prices, securityId filters, portfolioId sourced from get_portfolios). The description reinforces the securityId filter with the phrase 'look at a single position' but adds little syntax or semantics beyond the schema. Baseline 3 is appropriate when the schema does 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?

States a specific verb+resource (portfolio holdings) and enumerates the computed fields returned (market value, cost basis, realized/unrealized gain) plus the embedded security object. This is far more informative than a generic list tool. It doesn't, however, explicitly distinguish itself from siblings like get_portfolio_summary or get_portfolio_balances, so it stops short of a 5.

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

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

The only usage hint is 'Filter by securityId to look at a single position,' which is parameter usage rather than when-to-use guidance. There is no statement about when to prefer this over get_portfolio_summary, get_portfolio_balances, or get_portfolios, which are the obvious alternatives in the sibling set.

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

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

With no annotations, the description carries the full burden and delivers: it enumerates the returned fields (id, name, type, description, enabled state, creation date), which is valuable since no output schema exists. It does not mention pagination behavior or auth, keeping it short of a 5.

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

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

Two sentences, tightly front-loaded with the core purpose, then return shape, then downstream usage. 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 4-param, no-output-schema list tool this is nearly complete: purpose, return fields, and follow-up routing are all present. Only pagination semantics and the enabled/type filter semantics go unmentioned, which is minor given 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 limit, offset, isEnabled, and portfolioType are already documented with the type enum inline. The description adds no format or semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (user's investment portfolios), and distinguishes from drill-down siblings like get_portfolio_summary and get_portfolio_holdings. An agent can tell exactly what this returns without opening the schema.

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

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

Explicitly routes the agent forward: 'Use the returned id with get_portfolio_summary, get_portfolio_holdings, get_portfolio_balances, and get_investment_transactions.' This is clear context for a list-then-drill workflow, though it offers no when-not or filter-selection guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It adds genuine context ('All monetary values are decimals in the user's base currency'), which is useful, but says nothing about permissions, read-only nature, or rate limits. Adequate but incomplete for an annotation-free 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?

A single well-formed sentence that is front-loaded with the scope ('portfolio-level aggregates for a single portfolio') and then the returned fields. No wasted words, though the trailing currency note could be more tightly integrated.

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

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

With no output schema, the description takes on the job of explaining return values, and it does so by enumerating the aggregate metrics returned. Combined with the base-currency/decimal note, an agent knows what to expect. It would be complete at 5 if it also clarified the date-snapshot vs latest-price behavior.

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

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

Schema description coverage is 100%, so both parameters (portfolioId and date) are already fully documented in the schema, including the reference to get_portfolios. The description adds no parameter syntax or format detail beyond what the schema supplies, 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?

States a specific resource ('portfolio-level aggregates for a single portfolio') and enumerates exactly what it returns: market value, cost basis, realized/unrealized gains, cash balances, and total value. This is far more than a tautology. It falls short of a 5 because it never distinguishes itself from close siblings like get_portfolio_holdings or get_portfolio_balances.

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

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

The description implies usage by listing the aggregate fields, but never states when to choose this over get_portfolio_holdings, get_portfolio_balances, or get_portfolios. There is no when-to-use, when-not, or alternative 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?

With no annotations, the description carries the full burden, and it does disclose two useful traits: the per-category-total return shape and the current-month default window. It omits other behavioral context such as whether values are aggregated across accounts, currency, rounding, or sorting of results, so the safety/behavior profile is only partially covered.

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

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

Four short sentences front-load the core behavior and return shape, with no wasted preamble. The sentence 'Great for understanding where money goes' is promotional filler rather than actionable information, which keeps it just short of a 5.

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 6-parameter, flexible read tool with no output schema and no annotations, the description supplies the essential return format and default window, which is genuinely needed. It still leaves gaps around multi-filter interaction, aggregation scope, and result ordering that an agent would benefit from knowing.

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 every parameter (accountId, categoryIds, excludedCategoryIds, transactionType, dates) is already documented in the schema. The description only restates the date range and the current-month default, adding nothing about the filter interplay, so the baseline 3 applies.

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

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

The description names a specific verb+resource ('Get spending breakdown by category for a date range') and states the return shape ('each category with its total amount'). It is clearly distinguishable from generic list tools, though it never names the adjacent analysis siblings (get_budget_spending_stats, get_expenses_for_period, get_cash_flow) that an agent could confuse it with.

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?

'Defaults to current month expenses' and 'Great for understanding where money goes' imply an analytical/browsing use case, but there is no explicit when-to-use or when-not-to-use guidance relative to the sibling spending/expense tools. Usage must be inferred from the phrasing rather than stated.

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

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

No annotations are present, so the description carries the full burden. It does usefully disclose the response payload (linked transactions with match source and date, plus a computed next expected payment date), which is real value beyond the name. However, it says nothing about permissions, behavior when the ID is unknown, or whether the read is paginated.

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

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

One sentence, front-loaded with the verb and resource, and every clause (linked transactions, match source and date, next expected payment date) conveys distinct information. No filler.

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

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

With no output schema, the description compensates by enumerating the returned fields, which is exactly what an agent needs to interpret the result. It is close to complete for a one-parameter read; only error/edge-case behavior is unaddressed.

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