JaKonto

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

The annotations already declare readOnlyHint=false and idempotentHint=true, but the description adds meaningful context: the write only lands as a DRAFT awaiting human approval and never touches the accounting ledger, which reconciles the apparent tension of a non-read-only tool. It also sharpens idempotency with a scope qualifier ('per open finding') that the bare annotation does not convey. It stops short of explaining what happens to existing drafts or what the call returns.

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, followed by the safety guarantee and the idempotency note. Every sentence carries distinct information and none restates 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?

For a one-parameter tool with rich annotations, the safety and idempotency picture is complete, but two gaps remain: 'anomalies' is never defined, and with no output schema the description says nothing about what is returned (count of proposals, their identifiers, or an empty result). An agent knows it is safe to call but not what to expect back.

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 is fully covered ('Id from list_connections'), so the schema does the work. The prose adds nothing about connection_id or how scan scope is determined by it, which is the expected baseline for a one-param tool with 100% coverage.

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

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

The description pairs a specific verb with a specific resource: it scans for anomalies and files them as DRAFT proposals in JaKonto. That clearly separates it from the read-only sibling list_proposals, though the description never names that sibling, so the agent must infer the pairing.

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

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

Usage is implied rather than stated: 'for a human to approve' suggests this is the initiation step of a proposal workflow, and 'Never writes to the accounting system' reassures about scope. However, there is no explicit when-to-use or when-not-to-use guidance, and no indication of prerequisites such as whether connections must first be verified via list_connections.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real value by disclosing that results are scoped to the API key's permissions and by enumerating the returned fields, though it says nothing about ordering, pagination, or empty-result behavior.

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 compact sentence, front-loading what the list contains before the examples and the field enumeration. No filler and nothing 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 zero-parameter read tool with no output schema, describing the returned fields (id, system, company) is exactly the compensating detail needed. Only minor gaps remain, such as result ordering and what an empty list implies for the key's permissions.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description wisely spends its space on return shape instead.

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 resource (accounting systems/connections) and gives concrete examples (e-conomic, Dinero, Billy) plus the returned fields (id, system, company), so an agent can distinguish it from siblings like list_invoices or profit_and_loss. It lacks an explicit verb ('list'), but the enumeration framing makes the read intent unambiguous.

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

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

Usage is only implied: the phrase 'this API key can read' suggests a discovery/scope-check call whose ids feed other tools, but the description never states when to call it versus siblings or that it is a prerequisite for connection-scoped operations. No exclusions or alternatives are given.

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, non-destructive, closed-world behavior, so the description's job is supplementary — and it does add real value by disclosing the data model and the currency unit (øre), which prevents unit-interpretation errors. Pagination behavior is disclosed but page size and the terminal/short-page condition are not.

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 what the tool returns, followed by the one operational instruction. No wasted phrasing.

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 read-only list tool with no output schema, the definition covers the essentials: data model, units, and pagination handoff. It stops short of describing ordering, default page size, or what an empty/terminal page looks like, which an agent may still need.

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 only 50%, and the description fills exactly the gap: it explains that 'cursor' is fed from a previously returned 'next_cursor', which the bare schema does not say. connection_id is covered by the schema itself, so nothing further is needed there.

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 resource ('invoices from the accounting system') and the scope ('one page'), plus a notable qualifier ('canonical model, amounts in øre'). It does not explicitly contrast itself with siblings like list_proposals, but the resource noun is distinct enough for an agent to pick it 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?

The only usage instruction is procedural pagination ('Pass next_cursor back as cursor for the next page'). There is no guidance on when to choose this tool over the sibling list/profit tools, no mention of escaping the loop or what happens at the last page.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful scoping fact that results include proposals past human review, but says nothing about ordering, volume, pagination, or what 'past review' means in practice.

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?

It is short and wastes no words, but a single sentence fragment is under-specified rather than efficient. There is no leading verb or structure to front-load what the tool returns.

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

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

For a tool with a required connection_id and an unconstrained status string, the description does far too little: it never explains valid status values, default behavior when status is omitted, or the shape of the returned proposals. There is no output schema to compensate, so these gaps fall on the description.

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

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

Schema coverage is only 50%, and the undocumented parameter is precisely the important one: 'status' is a bare string with no enum and no description, so its accepted values are unknown. The description mentions review states but never maps them to the status parameter, leaving the most consequential input entirely unexplained.

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 is a noun phrase ('Bookkeeping proposals waiting for (or past) human review') with no verb, so the listing action is only implied by the tool name. It does narrow scope to proposals pending or past review, which distinguishes it from create_proposals, but an agent must infer that it returns a list rather than, say, a count or a single item.

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 explicit when-to-use statement and no mention of alternatives; the parenthetical '(or past)' hints that the tool covers more than just pending items but never clarifies that boundary. Nothing says when an agent should call this versus list_invoices or profit_and_loss.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that by saying what the response contains (revenue and expense lines plus a result) and the unit (øre), which matters since there is no output schema. It does not disclose accrual basis, whether zero lines are included, or rounding behavior.

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

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

A single front-loaded sentence that identifies the report, its time scope, and its contents with no filler. It is lean to the point of omitting guidance an agent would want, but nothing written 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 three-required-parameter read-only report with no output schema, the description covers the essentials: what it produces and in which unit. Gaps remain around range semantics, currency/accounting basis, and how it differs from vat_by_quarter, which matter 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 only 33% (only connection_id is documented, pointing to list_connections). The phrase "for a period" implies date_from/date_to form an inclusive range, which is a small but real addition; however, it clarifies neither boundary inclusivity nor timezone/format expectations beyond the schema's date format.

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 a specific resource (Resultatopgørelse / profit and loss) and states its scope ("for a period") plus the contents returned (revenue and expense lines, result in øre). An agent can tell this is a financial statement report rather than an invoice or VAT listing tool. It stops short of explicitly contrasting with vat_by_quarter, so it is clear but not fully sibling-differentiated.

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 mention of alternatives such as vat_by_quarter, which is the closest sibling and could plausibly be confused with this report. The only usage signal is the implied date range in "for a period".

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered without description help. The description adds genuinely useful context beyond that: the data source (synced invoices) and the currency unit (øre), which prevents unit errors. It stops short of disclosing return shape, whether empty quarters appear, or staleness of the synced 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?

A single front-loaded sentence with no filler; every element (metrics, granularity, unit, source) carries information. It could be marginally stronger by leading with the verb's object or adding one clause on when to prefer it over profit_and_loss.

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

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

The tool is simple (2 params, read-only), but there is no output schema, so the description bears responsibility for conveying the return shape. It names the three metrics and unit but not whether the result is a quarter-keyed map or array, whether all four quarters are always present, or how missing data is represented.

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

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

Schema description coverage is 100%, so both parameters (year, connection_id) are already documented, including the 'Default: this year' behavior and the pointer to list_connections. The description adds only the implicit framing that the year scopes a per-quarter breakdown, which the schema does not spell out. Baseline 3 is warranted.

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

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

States a specific verb-and-resource combination: it outputs three named VAT figures (output VAT, input VAT, VAT payable) at a stated granularity (per quarter) in a stated unit (øre) from a stated source (synced invoices). The purpose is unambiguous, but it does not differentiate itself from the sibling profit_and_loss report, which likely overlaps in financial-reporting intent.

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: an agent can infer this is the tool for period VAT reporting and that 'synced invoices' means data must already be synced via a connection. There is no explicit when-to-use, no exclusion of profit_and_loss for overlapping queries, and no statement of what happens if the connection has no synced data.

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