McpStamp Cash Book

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false and idempotentHint=false, so the safety profile is partly given. The description adds two things the annotations cannot: that nothing is written back to the source stores (resolving the tension between 'register it' and readOnly=false), and a concrete quota of 3 periods per month. It still does not say what a second identical call does, despite non-idempotent being hinted.

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, front-loaded with the verb and resource, then the source stores, then the write-scope and quota caveats. No filler or repetition of the title.

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?

Covers inputs and write scope well, and there is no output schema to restate. But with no output schema the description should indicate what a successful run yields (ledger id, line count, status), and it says only 'register it'; non-idempotent re-run behavior is also left for the agent to infer.

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 'from'/'to' formats and the conditional currency rule already documented in the schema. The description reinforces 'ONE currency' and the no-conversion rule, but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Derive') and resource ('the double-entry ledger for one period in ONE currency'), names every source store it aggregates, and adds that it 'registers' the result. This clearly separates it from siblings such as ledger_lines, ledger_report, trial_balance and month_close.

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 usage through the period/currency scoping and the quota note ('Free: 3 periods a month'), which signals a per-period batch operation. However, it never says when to prefer ledger_build over ledger_report, trial_balance or month_close, and gives no prerequisites or exclusions despite a rich 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?

Annotations already declare read-only, idempotent, non-destructive behavior, yet the description adds genuinely new context: the result is a download link with a one-hour validity window and one row per leg. It stops short of stating any rate limits or what happens when the link expires, so it is strong but not exhaustive.

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, zero filler, with the output format and link lifetime front-loaded before the sibling comparison. Every clause carries information an agent needs to choose or call the tool.

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

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

There is no output schema, and the description compensates by describing the return artifact (CSV via download link, one hour validity). Combined with full schema coverage of the five parameters, nothing material is missing for a read-only export tool.

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

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

Schema coverage is 100%, with from/to/source/account/currency all documented in-schema including the multi-currency rule, so the schema does the heavy lifting. The description adds only the row granularity ('one row per leg') and says nothing about the required date range or filtering parameters, 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 ('Return the period's ledger lines') plus the output format ('RFC 4180 CSV, one row per leg, as a download link'). It explicitly distinguishes itself from the sibling ledger_lines, so an agent can separate the two 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 (ledger_lines) and the exact condition that selects it: the same fields are free and unlimited there, and this tool only re-lays them out as CSV columns. That is an explicit when-to-use/when-not-to-use rule rather than an 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?

The description adds real behavioral content the annotations do not: each row carries debit, credit and bank_ref, the response includes totals of the rows returned, and filtered totals do not balance. But it frames the tool as a pure read ("List") while annotations declare readOnlyHint=false, leaving the agent unsure whether the call has side effects — a discrepancy that matters more than the extra detail helps.

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 dense sentence front-loads the action and the filters, and two short clauses add the totals caveat and cost. Nothing is redundant, though "Free." and "source server" are terse enough to need a second read.

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 discloses the row shape (debit, credit, bank_ref) and that totals are returned, which is exactly what an agent needs to plan the call. Gaps remain around pagination/limit behavior and the currency requirement, though both are covered in the schema.

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

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

Schema description coverage is 100%, so all nine parameters are already documented in the schema, and the description only restates the filter set (account, source, source_id, date) without adding format or interaction detail. Baseline 3 applies where the schema carries the 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 a specific verb and resource ("List the ledger lines for a period") and enumerates the supported filters (account, source server, source_id, date), so an agent can tell this returns individual ledger entries rather than an aggregate. It stops short of naming siblings such as trial_balance or ledger_report, so the boundary with those tools must be inferred.

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?

"Filtered totals do not balance" is a useful warning that steers an agent away from treating filtered output as a reconciliation figure, which implicitly points to trial_balance for balanced totals. However, there is no explicit when-to-use/when-not-to-use guidance or named alternative, so routing 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety behavior is covered. The description usefully adds that memos/purchase commitments and exceptions are folded into the report and that the period must already exist, but it doesn't say what happens if the requested period was never built or what the output shape is.

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?

Output scope is front-loaded in the first sentence, which is good. The second sentence is marred by the garbled "Pro;" token and a compressed sibling pointer that costs clarity without saving much space.

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

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

For a read-only, three-parameter report with no output schema, the description does the important work of enumerating the returned figures. It still leaves gaps an agent would care about: the failure mode for an unbuilt period, how multi-currency periods are presented, and the meaning of "exceptions".

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 from/to formatting and the multi-currency rule are already fully documented in the schema. The description reinforces the period concept ("built period", "the period's exceptions") but adds no syntax, defaults or constraint meaning beyond what the schema 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?

The verb+resource is specific: it reports a period account by account and enumerates the outputs (debits, credits, movement, closing balance, purchase-commitment memos, exceptions), which clearly separates it from ledger_lines. The dangling fragment "Pro;" is confusing and slightly muddies an otherwise precise statement of 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?

"a built period" implies a prerequisite (the period must have been built, presumably via ledger_build), and "ledger_lines gives the lines free" points at the alternative for line-level detail. However, neither is stated as an explicit rule — there is no "use this when / don't use this when" and no mention of what to do if the period is not yet built.

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 non-read-only, non-destructive, non-idempotent, closed-world. The description adds real value beyond that: the effect is scoped to 'this connection', existing data under the token is preserved, and a wrong or expired key is a no-op. It does not say whether the change is immediate or whether repeat activation is harmless, which is relevant given idempotentHint=false.

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

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

Two short sentences, front-loaded with the effect and followed by the failure guarantee and verification pointer. No filler or restated boilerplate.

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, no-output-schema tool with annotations covering the safety profile, this is close to complete: effect, scope, failure behavior, and a verification sibling are all covered. Only minor gaps remain (immediacy of effect, behavior when already licensed).

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 single param already documents the MCPL1 format, so the baseline is 3. The description earns an extra point by adding provenance the schema lacks: the key is issued at checkout and must be for this server or the bundle.

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

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

The description names a specific action (turn Pro on) and its scope (for this connection), plus the exact credential shape required. It also positions the sibling license_status as the verification path, so an agent can distinguish activation from status checking 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?

It states the precondition clearly: the key must be an MCPL1.<payload>.<signature> token issued at checkout for this server or the bundle, and directs verification to license_status. It stops short of explicit when-not-to-use guidance (e.g., what to do if already Pro or if the key is for a different server).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context beyond annotations by specifying the JSON response contents and stating 'nothing changes,' reinforcing the read-only nature of the call.

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

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

Two dense sentences cover output, purpose, usage context, and side-effect guarantee. Every sentence earns its place and the most important information is front-loaded.

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

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

With no output schema, the description sufficiently describes the return value. With no parameters, annotations covering safety, and a clear use case, nothing essential is missing for an agent to invoke this tool correctly.

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

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

There are zero parameters and the schema already fully documents that fact. The description explicitly says 'No arguments,' which is accurate and reinforces the schema without needing further elaboration.

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 begins with a specific verb ('Report') and a precise resource ('this endpoint's licence state for your token'), and enumerates the exact output fields: product, tier, reason, and checkout URL. This clearly distinguishes it from sibling tools like license_activate.

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

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

The description explicitly states when to call it: 'Call it to explain a free-tier refusal.' This is clear contextual guidance, though it does not name alternatives or explicitly state when not to use it.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive, closed-world. The description adds real value beyond that: it discloses that a snapshot is persisted and can be compared against later, and that dry_run is a no-write path. It does not explain what happens on a second close of the same month, despite idempotentHint=false, nor any permission or 'Pro' tier requirement implied by the trailing token.

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?

Very compact: the artifacts and the snapshot consequence are front-loaded, then the dry_run caveat, then a licensing flag. Nothing meaningful is padded. Points off only for the telegraphic single-sentence construction and the unexplained 'Pro.' fragment, which reads as leftover metadata.

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 mutating, non-idempotent close with no output schema, the description covers what gets written and the dry-run escape hatch, which is the essential shape. It leaves open the re-close/overwrite semantics and any response details, and the 'Pro' suffix is not decoded into a prerequisite an agent could act on.

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 month format, dry_run default, and the currency rule about periods holding multiple currencies. The description only restates dry_run's no-write behavior, which the schema's own field description already covers, and says nothing about currency. 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 the concrete artifacts produced: unposted/unbalanced exceptions, trial balance, bank reconciliation, plus a stored close snapshot with later drift detection. That distinguishes it from the read-only sibling trial_balance and from period_delete. It stops short of 5 because the core verb is expressed obliquely ('List what a month leaves... then store the close') rather than stated outright, and the trailing 'Pro.' is unexplained noise.

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 one useful selector: 'dry_run writes nothing', which signals a preview path before committing. It also implies a two-call workflow (close now, later call to check drift) without saying how to trigger that check. No alternatives are named, so an agent gets no explicit direction to period_delete or trial_balance.

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

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

Beyond the annotations' destructiveHint/idempotentHint, the description discloses the quota consequence (free-tier slot released), the guard condition that blocks deletion, and that the blocking month is named in the refusal. That is exactly the extra context an agent needs before firing a destructive call, and it also scopes the blast radius.

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 action and its payoff, followed by the refusal rule and scope note. No sentence 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 three-parameter destructive toggle with a fully documented schema and no output schema, the description covers purpose, guard condition, and side effects. The only minor gap is what a successful call returns, which the absence of an output schema makes low stakes.

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 from/to date formats and the conditional currency requirement are already fully documented in the schema. The description refers only to "the period" without adding format or disambiguation detail, so it meets but does not exceed the baseline.

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

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

"Delete one built period from the register" gives a specific verb plus resource and narrows scope to a single period, so it cannot be confused with ledger_build or month_close. The quota side effect ("give its free-tier slot back") further fixes what kind of delete this is.

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

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

The description states a concrete when-not condition (refused when a closed month's snapshot covers the period) and clarifies blast radius with "No sibling book is touched." It does not name a sibling alternative to use instead, but with no competing delete tool in the set there is little to route between.

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

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

Beyond the annotations, the description discloses the out-of-balance behavior (it returns the offending entries plus their source documents) and the cost profile ('Free and unlimited'), which is genuinely useful operational context. It stops short of describing return shape, ordering, or whether results are scoped per currency, so it does not reach a 5. The read-like framing sits in mild tension with readOnlyHint=false, but the text never asserts that nothing is modified.

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 primary action and its result, then the failure-path behavior, then cost. Nothing is redundant. Minor deduction only because 'prove they are equal to the minor unit' is dense phrasing that reads awkwardly for an agent.

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 three-parameter read-style computation with full schema coverage and no output schema, the definition tells the agent what the operation does, what it emits on failure, and that it is unmetered. Missing only comparative guidance against sibling tools, which is the one thing an agent would still 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 description coverage is 100%, so all three parameters are already documented in the schema, including the multi-currency caveat. The description's mention of 'for a period' and 'minor unit' echoes that without adding format 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?

States a specific verb-and-resource pair: total debits and credits for a period and prove they are equal. It also describes the secondary output (naming unbalanced entries and their source documents), which makes the tool's identity as a trial-balance check unmistakable. It does not explicitly contrast itself with siblings such as ledger_report or ledger_lines, which keeps it from 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?

There is no when-to-use guidance and no named alternative. An agent cannot tell from the description whether this should be run before month_close or instead of ledger_report, nor whether a period must be closed first. Only the implicit signal 'for a period' hints at usage.

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