PNL Toolkit

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

Annotations already declare the safe read-only, idempotent, closed-world profile, and the description adds real value on top: it generates a PNG artifact, returns results/conditions/assumptions/editable link/share page, and explicitly disclaims account access and order execution. It does not disclose rate limits or whether repeated calls accumulate artifacts, which is a minor 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?

Two compact sentences, front-loaded with the input model and then the outputs. Every clause carries information; it is dense but not 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?

With a full output schema and rich annotations already present, the description only needs to add scope and side-effect context, which it does (PNG creation, no account/order access). Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents every parameter with ranges, defaults, and units; the description only echoes the unit conventions (USD, percent, whole years). Baseline 3 is warranted since the description contributes little 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 and resource ('Compound interest in USD') and enumerates the input dimensions (initial dollars, monthly dollars, annual return/fees/inflation, whole years) plus the artifacts it creates. It never names or contrasts the close sibling dca_backtest, so sibling differentiation is left 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?

Lists what the tool consumes and produces but gives no when-to-use guidance or routing against siblings like dca_backtest, drawdown_recovery, or historical_return. The only scoping statement ('No account access or order execution') is a safety boundary, not a usage condition.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description adds real value beyond that: first purchase occurs at the selected start month-end, omitted dates use calculator defaults clamped to coverage, and no account access or order execution. It stops short of describing rate limits or full return shape, but the added behavioral detail is substantial.

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?

Reasonably front-loaded, but the sentence 'Returns data metadata and the free calc-dca PNG' is immediately followed by a near-duplicate 'Returns results, conditions, assumptions, an editable link, share page and PNG,' which wastes space and blurs the return-value statement.

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

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

With an output schema present and annotations covering the safety profile, the description needs only the sourcing caveat, timing rule, and default-handling note, all of which are present. It is largely complete for a no-required-parameter read-only backtest tool.

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

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

Schema description coverage is 100%, so all 10 parameters are fully documented in the schema, establishing a baseline of 3. The description largely restates those fields (ticker, start/end YYYY-MM, deposit USD, monthly USD, frequency, fee, benchmark, return basis) without adding format or constraint detail beyond what the schema and pattern/enum already supply.

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 ('Dollar-cost-averaging backtest') and immediately scopes it ('using installed monthly closes, not live quotes'). An agent can distinguish it from siblings like compound_interest or historical_return 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?

Implies the use case through the 'installed monthly closes, not live quotes' constraint and the DCA framing, but never states when to choose this over compound_interest or historical_return. No explicit alternatives or exclusion conditions are named.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, and the description reinforces this with 'No account access or order execution' — a meaningful safety boundary. It also discloses output artifacts beyond the annotation set (editable link, share page, PNG), though the exists-yet output schema already covers much of the return surface.

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 purpose and followed by inputs, outputs, and the safety boundary; every clause carries content. The telegraphic 'balances/deposits in USD, drawdown and monthly return in percent' phrasing is dense enough to be slightly ambiguous, which keeps it from 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?

With 10 optional parameters, a 100%-covered schema, and an output schema present, the definition only needs to convey unit conventions, scope, and the non-trading boundary — and it does all three. The scenario modes and how they interact with loss/losses/current are left entirely to the schema, 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%, so the schema itself documents every parameter, including units and ranges; baseline 3 applies. The description restates unit conventions (USD, percent, whole months) but adds no format, default rationale, or interaction details beyond what the input schema already gives.

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

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

The description names a specific resource (drawdown recovery calculation) and enumerates the input dimensions it works on — balances/deposits, drawdown, monthly return, target horizon. That is clearly distinct from sibling calculators like compound_interest or dca_backtest, but no sibling is named or contrasted, 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?

Usage is only implied: the scenario enum values (drawdown/balance/streak) and the recovery framing suggest when the tool applies, and the 'No account access or order execution' line sets a scope boundary. There is no explicit statement of when to choose this over compound_interest or dca_backtest, nor any prerequisite guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds rich context: it uses installed monthly closes, applies date clamping to coverage, returns coverage/source metadata, results, assumptions, an editable link, share page, and PNG, and explicitly states no account access or order execution. This exceeds the annotation profile with useful operational detail.

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

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

The description is front-loaded with purpose and key parameters, then outputs and scope limits. It is somewhat dense and could be split for readability, but every sentence carries information. Minor redundancy in listing outputs twice.

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 9 parameters, no required fields, and an output schema, the description provides enough context: it explains data source, date clamping, output artifacts, and absence of side effects. It does not detail return fields, but the output schema covers that. Slightly more guidance on sibling alternatives would improve completeness.

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

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

Schema coverage is 100%, so the schema fully documents all parameters. The description summarizes key inputs (asset, dates, amount, unit, fee, benchmark, basis) but adds little beyond what the schema already provides. Baseline 3 is appropriate when 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: computes historical investment return from installed monthly closes, not live quotes. Distinguishes from siblings by noting it uses snapshot data. However, it doesn't explicitly differentiate from dca_backtest, which likely also computes historical performance, leaving some sibling ambiguity.

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

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

The description implies use for historical performance calculation with optional benchmark and return basis. It does not state when to choose this over dca_backtest or compound_interest, nor does it provide explicit exclusions or prerequisites. Usage context is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world status, so the safety bar is partly met. The description adds real value beyond them by enumerating outputs (results, conditions, assumptions, editable link, share page, PNG) and explicitly stating no account access or order execution.

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

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

Three dense sentences, front-loaded with the unit conventions and followed by outputs and safety scope. Almost every clause earns its place, though the opening verb-less phrase is slightly weaker than a direct purpose statement.

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

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

An output schema and full annotation set already carry return-shape and safety burden, and the description reinforces this with units and an explicit no-execution note. It is complete enough for an agent to invoke, with the only gap being absent routing guidance versus sibling calculators.

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 consolidates units across parameters (mid/tick in USD, weights in percent, spread/skew/cap in bps) and re-explains skew, but this largely overlaps what the schema already documents per field rather than adding new semantics.

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

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

The description opens with "Inventory quotes," which essentially restates the tool name rather than stating a clear verb+resource, and it never distinguishes itself from siblings like spread_and_fees. The unit mapping and return description do convey that this computes inventory-based quotes, so the purpose is inferable but not crisply actionable.

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

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

There is no when-to-use guidance, no conditions, and no reference to sibling tools such as spread_and_fees. The line "No account access or order execution" scopes behavior but does not tell the agent when to pick this tool over alternatives.

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

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

Annotations already cover readOnly, idempotent, non-destructive, and closed-world behavior, so the bar is lower. The description still adds real value by naming the return artifacts ('results, conditions, assumptions, an editable link, share page and PNG') and explicitly disclaiming side effects ('No account access or order execution'), which reassures an agent this is a pure calculation.

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 tightly packed sentences with the core purpose front-loaded and no filler. The unit enumeration in sentence one is dense but each clause maps to real parameters, so it earns its place. Minor cost: the unit list reads like a schema echo rather than new 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 an output schema present, the description needn't explain return values, yet it still summarizes them usefully. All 11 params are optional and fully described in the schema, and the safety profile is covered by annotations. The only missing element is sibling routing, which is a usage-guideline concern rather than a completeness 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 the schema already documents all 11 parameters with defaults, bounds, and units. The description's unit summary (USD prices, percent risk, basis-point fees, unit increments) largely restates what the schema provides and adds no syntax or edge-case semantics 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 states a specific operation and resource: 'Position sizing for linear USD shares/coins', followed by the unit conventions it operates in. An agent can tell what it computes, but nothing distinguishes it from conceptually adjacent siblings like trade_expectancy or inventory_quotes (the latter only surfaces in the schema for the 'target' param, not the description).

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 routing to alternatives among the seven siblings. The unit conventions hint at legitimate inputs but never say under what conditions this tool should be chosen over trade_expectancy or inventory_quotes. The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes further by disclosing the units convention, that negative fees are rebates, and what artifacts come back (results, conditions, assumptions, editable link, share page, PNG) — meaningful behavior beyond the annotations.

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

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

Two dense sentences with zero filler: the cost model is front-loaded, then output artifacts and the safety boundary. Every clause carries information.

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

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

With an output schema present and annotations covering the safety profile, the description need not explain returns or permissions; it supplies units, sign conventions and the no-execution caveat. Adequate, though it omits any mention of error conditions or input validity limits.

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 five parameters, including defaults and ranges. The description adds the 1 bp = 0.01% conversion and restates that negative fees are rebates, marginal extra value over the per-parameter docs.

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

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

The phrase 'Round-trip spread economics' names a specific domain and the three modeled cost components (spread, fee, adverse), which distinguishes it from siblings like trade_expectancy and compound_interest. It is clear but never explicitly contrasts itself with those alternatives.

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

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

Usage is only implied by the cost-model framing; there is no statement of when to pick this over position_size or trade_expectancy. The closing boundary 'No account access or order execution' usefully scopes it out of live-trading territory, which partially compensates.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds a scope boundary (no account access, no order execution) that clarifies it is a stateless computation. It complements rather than repeats the annotations, though it does not add auth or rate-limit context.

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

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

Two dense sentences, front-loaded with the computation and its units; every clause maps to real content. The payoff list in sentence two is slightly verbose given an output schema exists, 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?

For a calculator with 9 optional, fully-defaulted params, an output schema, and safety annotations, the definition gives enough to call it correctly. The only real gap is sibling routing, which a purely computational tool can partly afford to omit.

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

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

Schema description coverage is 100% and the schema already documents each parameter's unit, so the description's unit groupings largely restate structured data. The compressed 'fraction 0–1' and buffer/cap framing adds marginal value, fitting the 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?

Names the specific computation (trade expectancy and fractional Kelly) and enumerates each input group with its unit, so an agent knows exactly what the tool computes. It does not explicitly distinguish itself from calculator siblings like position_size or compound_interest, which keeps it 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 trailing clause 'No account access or order execution' signals this is a pure calculator rather than a trading action, implying usage. However, it never states when to pick this over position_size or the other calculators, so guidance is only implied.

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