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

With no annotations, the description carries the full burden and does disclose real behavior: it mutates the year's expenses tab, rejects duplicates, and blocks writes to filed quarters. It does not cover permissions/auth, error shapes, or what dry_run actually returns, which leaves a 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?

Three sentences, front-loaded with the effect, then the field list, then the guardrails and dry-run instruction. Every clause carries information an agent needs before calling.

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 definition covers effect, field set, and refusal conditions. The remaining gap is the return behavior of dry_run and real runs, which an agent would want before deciding to proceed.

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 0% and the row object is a free-form nested object, so the description must compensate — and it does by enumerating all sixteen expected keys plus the date format (YYYY-MM-DD). It stops short of explaining the meaning or expected type of opaque keys like fx, business_pct, nif, and code.

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 with scope: 'Add one expense row to the year's expenses tab.' An agent can immediately tell this from add_income or propose_income by the resource named. It doesn't explicitly name a sibling to differentiate against, keeping it just below 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 concrete prerequisites and workflow: deduplication, refusal on already-filed quarters, and 'Call with dry_run=true first.' That is actionable when-to-use guidance. It lacks an explicit when-not or a pointer to alternative tools for bulk/other 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 full burden and partially discharges it: it discloses the duplicate/filed-quarter guards, the dry-run default, and the shape of the write. It does not say what a refusal returns, whether partial rows are accepted, or whether the write is reversible.

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 required payload, then the guardrails. The long key list is long but justified by the empty 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?

No annotations and no output schema, so the description must cover everything; it covers the payload and some failure modes but not the dry-run response, error semantics, or how amount/currency/fx combine. Adequate but with real gaps for a mutation 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 0% and the row object is opaque (additionalProperties: true), so the enumerated key list is essential and includes a format hint (invoice_date YYYY-MM-DD). Meaning of individual fields (fx, net_eur, vat_case, withheld) is still left to inference, keeping it below 5.

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 sale to the year's income tab.' That cleanly separates it from add_expense (outflow) and propose_income (proposal vs. commit), though it never names those siblings explicitly.

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?

'Dry run first' gives a concrete workflow directive, and 'Refuses duplicates and filed quarters' implies when it will fail. But there is no explicit statement of when to use this versus propose_income or how to handle a refusal.

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. It usefully discloses a safety behavior ('Refuses to overwrite') and the content it generates (tables, quarter sums, formulas, dropdowns), but silently omits that dry_run defaults to true, which determines whether anything is actually written, and gives no indication of required auth/config or where the file lands.

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 outcome, then the contents, then the default and the guardrail. Dense but every clause conveys something; the domain jargon (box 61/96, Declaração Periódica) slightly raises reading cost.

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?

It is a mutation-style creation tool with no annotations and no output schema, so the description should cover the default-dry-run trap and what is returned (file path or sheet URL). It covers generated content well but leaves those two agent-critical 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 coverage is 0%, so the description must compensate. It does explain opening_credit meaningfully (Q1 box 61, defaults to previous year's Q4 box 96), but 'year' is left implicit and dry_run — the single most consequential parameter given its true default — is never mentioned.

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 concrete verb+resource ('Create a tax year's books') plus the output artifacts (.xlsx workbook or Google Sheet tabs). It distinguishes itself from the read/analysis siblings (vat_return, index_year, income_totals) by being the constructor, though it never names an alternative explicitly.

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 context is implied ('per the config', 'refuses to overwrite', default opening credit from prior year Q4 box 96), but there is no explicit when-to-use vs when-not guidance and no pointers to siblings like index_year or add_expense once the sheet exists.

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 useful behavioral details: extraction layers, return contents, and the safety behavior of withholding text for non-invoice PDFs unless read_anyway=true. It still does not explicitly confirm read-only behavior or describe error handling.

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, then returns, then conditional behavior. Each sentence earns its place despite the dense return-value list.

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 complex extraction tool with no annotations, no output schema, and 0% schema coverage, the description does well on purpose and return behavior. It remains incomplete regarding path semantics, read-only guarantees, and error conditions.

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 0%, and the description explains the read_anyway parameter well in context. The required path parameter is only indirectly described as pointing to one invoice or receipt, without format or path details.

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

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

The description states a specific verb and resource: read one invoice or receipt (PDF or photo). It also specifies what is returned, but it does not explicitly differentiate this tool from siblings such as read_efatura or scan_inbox.

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

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

The use case is implied by 'Read one invoice or receipt' and the read_anyway condition is explained. However, there is no explicit guidance on when to choose this tool over sibling tools like read_efatura or scan_inbox.

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 duplicate-collision rule (inbox copy deleted instead), the safety invariants (never overwrites, never deletes outside the inbox), and the special-case routing for e-Fatura CSV. It omits permissions requirements and what the tool reports back after filing or deleting.

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 primary action, then conditions and safety invariants in short declarative sentences. Every sentence adds a distinct rule; nothing is repeated from the schema or 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 3-parameter mutation tool with no annotations and no output schema, the description covers behavior, edge cases, and safety well. The remaining gap is return-value information — what the caller sees after a file, a skip, or a dry run — which nothing else supplies.

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 0%, so the description must compensate, and it names the role of each parameter: the inbox document (`path`), the name override (`name` defaulting to the proposed name), and the preview mode (`dry_run`, via "Dry run first"). It stops short of clarifying whether `path` is absolute or inbox-relative and what a dry run actually returns.

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: moving a document out of the inbox into its tax-year folder. It names the destination, the naming rule, and the special e-Fatura CSV routing, which cleanly separates it from siblings like scan_inbox, plan_inbox, and mark_filed.

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?

"Dry run first" gives an explicit ordering instruction, and "under the proposed name (or `name`)" implies this follows a prior planning step. It does not, however, name the sibling that produces the proposal (plan_inbox) or state when not to use this tool, so alternatives remain inferred 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?

With no annotations, the description must carry the behavioral burden. It usefully discloses the date basis (invoice date for IRS, recibo date for Segurança Social) and quarterly/yearly granularity, implying a read-only reporting operation, but it does not explicitly state that it is non-mutating or mention any prerequisites.

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 single sentence is front-loaded with the key resource and uses a colon list to add precise categories. It is dense but contains no obvious 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?

An output schema exists, so return values need not be explained, and the description covers the data categories and quarterly/yearly scope. However, with no annotations and 0% schema coverage for the sole parameter, it omits required year semantics and explicit behavioral guarantees.

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 0%, and the description never mentions the required 'year' parameter or explains its format or meaning. It only refers to 'the year' as part of the output scope.

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

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

The description clearly states the resource: IRS and Segurança Social totals per quarter and for the year, broken down into gross income by invoice date, income by recibo date, and business expenses. It lacks an explicit verb and does not differentiate from sibling tools, but the intended output 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 guidance on when to use this tool versus alternatives such as add_income, propose_income, or vat_return. Usage is only implied by the phrase 'at the top of the income tab'.

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 does disclose that this mutates the ledger and is a prerequisite for dedup recognition, plus the rerun condition. It does not say whether reruns are idempotent, whether existing entries are overwritten, whether source files are touched, or what happens on partial 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?

Two short sentences with no filler; the operative behavior comes first and the run cadence follows. The cadence and rerun condition are packed into one sentence but remain readable.

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 mutation with no annotations and no output schema, the definition covers what it does and when to run it, but leaves the agent guessing about idempotency, side effects on files, and the result. Adequate but with clear 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?

There is one required parameter with 0% schema description coverage, so the description must compensate. 'The year's folders' and 'once per year' imply the parameter selects a fiscal year's folder set, but the expected format (e.g. 2024 vs 24) and scope are never specified.

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 concrete verb and outcome: reads every existing document in the year's folders into the ledger. The phrase 'so later copies are recognised' explains the point of the operation, making the tool's role distinguishable in concept from scan_inbox or file_document, though no sibling is named directly.

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?

Explicit cadence guidance: 'Run it once per year (and again after moving files by hand)' tells the agent exactly when this must be invoked. It lacks any when-not-to-use or named alternative, which keeps it below 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 does substantial work: it discloses that values are frozen, that locking is 'warning-only' (soft, not blocking), that PDF boxes are compared against the sheet, and that apply_pdf_values=true overwrites frozen values because the submitted return is the source of truth. It still leaves unstated whether a filing can be undone/unlocked and what the dry run actually reports.

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 mutation, then the PDF-comparison condition, then the operational directive 'Dry run first.' The second sentence is long and carries a stray line break, but every clause (locking target, overwrite precedence, dry run) adds actionable 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 5-parameter mutation tool with no annotations and no output schema, the description covers the mutation semantics well but omits what the tool returns or reports under dry_run, whether the filing is reversible, and the accepted quarter format. Given the tool irreversibly alters declaration state, at least the reversibility question should be answered 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 0% and the description does explain dry_run, return_pdf and apply_pdf_values in prose, including the overwrite precedence rule. However, the required 'quarter' parameter is a free string with no enum and the description never specifies accepted format (e.g. 'Q1' vs '1'), and 'year' is only alluded to via 'the year folder' — real ambiguity an agent could trip on.

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 action (freeze declaration values, grey and lock the quarter's block column, expense rows and income rows) triggered by a specific event (the user submits a quarter). The verb+resource is concrete, but it never contrasts itself with the many sibling tools (vat_return, file_document, index_year), so an agent must infer that this is the post-submission locking step.

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 ('After the user submits a quarter') and a sequencing instruction ('Dry run first'), which is genuine usage guidance. It stops short of naming alternatives or stating when-not to use it (e.g. when the quarter isn't submitted yet, or when the return PDF is absent and apply_pdf_values would be meaningless).

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 add real content by disclosing the specific checks performed (flagged rows, orphan files, duplicate receipts, missing months, income without AT documents). However, it never states that it is a read-only report, whether it writes anything to the sheet, or what the result looks like, leaving key behavioral traits unstated.

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 scope statement 'What is still missing for a year' is front-loaded, and each subsequent clause names a concrete check that adds information. The sentence is long and runs on, but nearly every clause earns its place as an enumerated check.

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, no-output-schema reporting tool, the description covers the substantive question an agent needs answered: what the report contains. Gaps remain around output shape and read-only behavior, but the core scope is 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 0% and the description only implies the sole parameter via 'for a year', without clarifying whether that means calendar year, a specific year sheet, or the expected format for the integer. The single parameter is at least semantically reachable, but the description does not compensate for the empty schema documentation.

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 enumerates the exact categories of gaps the tool reports (MISSING rows, unbooked files, duplicate receipts, missing subscription months, unbooked income sales), making its purpose as a diagnostic gap report clear. It lacks an explicit verb (list/report) and does not contrast itself with siblings like reconcile_efatura or index_year, but the enumerated checks distinguish it well enough.

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 enumerated checks suggest an audit/reconciliation scenario, but the description never says when to call this versus reconcile_efatura, vat_return, or index_year, nor does it state any preconditions. An agent can infer the intent but must guess at 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?

No annotations exist, so the description must carry the full disclosure burden. It does declare non-mutation ('without writing anything') and enumerates return categories, but says nothing about cost, volume, or latency even though 'read everything in the inbox' implies a potentially large scan, and nothing about permissions needed to read the inbox.

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 front-loaded sentence plus a colon-delimited enumeration: the action and the read-only guarantee come first, and the detail list follows. It is dense but each listed category corresponds to a downstream tool, so little 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?

Since there is no output schema, the description must describe the result, and it does so via the enumerated plan categories, which is adequate. Remaining gaps are what the 'checks' resolution means and how to tell which items are safe to file automatically.

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 is 4; there is nothing for the description to disambiguate. 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 and resource ('Read everything in the inbox and return the plan') plus the key constraint 'without writing anything', and enumerates the returned categories (expense rows, sales, documents to read, copies, non-invoices, e-Fatura exports). It never names the closest sibling (scan_inbox) to say how it differs, 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?

The routing is clear: expense rows are 'ready for add_expense' (with file names for file_document), sales are 'ready for add_income'. This makes it plainly the pre-flight planning step before those mutation tools. However, it never explicitly says when not to use it, nor contrasts it with scan_inbox or extract.

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 behavioral burden. It discloses what is returned and that the tool checks whether the two documents belong together, but it does not clarify side effects, permissions, error behavior, or whether anything is stored despite the 'propose_income' name.

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

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

The description is compact and front-loaded with the core action, then lists the returned data and validation behavior. It is appropriately sized, though the long parenthetical and dense return-field list make it slightly less scannable.

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 annotations, no output schema, and 0% schema description coverage, the description does a reasonable job covering the inputs, return fields, and document-matching check. It still leaves gaps around optional-parameter behavior, path semantics, and error or mismatch outcomes.

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 0%, so the description must compensate. It explains that the inputs are the user's invoice and/or the AT document (recibo verde, fatura, or fatura-recibo), which maps meaning onto the two path parameters, but it does not describe path format, defaults, or behavior when one path is omitted.

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 gives a specific verb and resource: 'Read one sale' involving the invoice and/or AT document, and says it returns the income row. It is clear enough to distinguish a read/check operation from a write operation, though it does not explicitly name sibling alternatives such as add_income.

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

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

The description implies the tool is used when reading one sale and checking whether the invoice and AT document belong together, but it does not state when to use this tool versus siblings like add_income, file_document, or income_totals. No exclusions or alternative routing are provided.

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 parses CSV data and produces documents with booking proposals, but does not disclose whether it writes to the system, whether proposals are persisted, whether the file is only read, or what happens on malformed 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?

The description is a single sentence with no wasted words and front-loads the action and result. It is appropriately sized for a one-parameter parsing 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?

The output schema exists, so return values do not need to be explained. However, with no annotations and only a terse statement, the description leaves important context unstated, including whether the operation mutates state by creating booking proposals and how it relates to sibling tools.

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 one required parameter, csv_path, with 0% schema description coverage. The description clarifies that the input is an 'e-Fatura CSV export', which adds useful meaning beyond the bare parameter name, but it does not specify path format, encoding, or expected CSV structure.

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: 'Parse an e-Fatura CSV export into documents, each with a booking proposal.' It is clear what the tool does and what it produces, though it does not explicitly distinguish itself from the sibling 'reconcile_efatura' or 'extract'.

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

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

The description implies the tool is for parsing e-Fatura CSV exports, but it gives no explicit when-to-use guidance, prerequisites, or alternatives such as 'reconcile_efatura' or 'extract'. An agent must infer the selection 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 and leaves the key question unanswered: is this a pure read/compare or does it write discrepancies into the sheet? Nothing is said about side effects, whether the expenses tab must exist, what happens on a missing/malformed CSV, or how the report is presented.

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 with no wasted preamble, front-loading the comparison before the parenthetical detail. The trailing list of discrepancy types is long but each item adds 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?

There is no output schema and no annotations, so the description must cover both behavior and result shape; it does the former partially (what counts as a mismatch) but not the latter (structure of the returned report), and it omits prerequisites and failure modes. Adequate to understand intent, insufficient to call confidently.

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 0%, so both parameters rest on the description — which never mentions them. It does not say what format csv_path expects (local path, upload dir, required e-Fatura columns) or that year selects which year's expenses tab is compared. A caller must guess at the CSV's expected shape.

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 gives a specific verb ('Compare') and both resources (an e-Fatura CSV export vs. the expenses tab), then enumerates the three discrepancy classes it surfaces. That enumeration effectively separates it from read_efatura or extract, though no sibling is named outright.

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 output categories — an agent can infer this is the audit step after an e-Fatura export exists. There is no explicit 'use when' statement, no prerequisite note (e.g. the year's expenses tab must already exist), and no guidance on when a different sibling like read_efatura or missing is the better first call.

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 real work: it discloses that listing involves classification (kind), content inspection ("whether a PDF reads like an invoice"), ledger-state lookup, and exact-duplicate detection — behavior an agent could not guess. It does not state cost/latency for scanning or explicitly confirm the operation is side-effect free, so it falls just short of full transparency.

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

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

Front-loaded with the action and scope, and the parenthetical enumerations of kinds and statuses are compact. The second half is a long run-on field list that could be tightened, but every element conveys real 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?

An output schema exists, so the return-value enumeration is partly redundant, but it usefully tells the agent what signals to look for (duplicate flags, invoice-likeness) before committing to follow-up tools. For a zero-parameter listing tool this is essentially complete; only the relationship to sibling workflow steps 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?

Zero parameters, so the baseline is 4; there is nothing to disambiguate and the description correctly avoids inventing filter arguments.

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 the files in the inbox folder") with an explicit scope and ordering (newest first), so it is immediately distinguishable from sibling tools like plan_inbox or index_year. It does not explicitly name a sibling it is not, but the inbox-listing scope 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?

Usage is only implied: an agent can infer this is the discovery step before extract, file_document, or plan_inbox, but the description never says when to reach for it versus those alternatives, nor any preconditions (e.g., whether the inbox path must exist).

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 of behavioral disclosure. It describes domain content but does not state that the tool is read-only, what the return structure looks like, or any auth/side-effect constraints.

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 a single front-loaded sentence with no redundant text. That is appropriately terse for a simple zero-parameter reference 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 zero parameters and no output schema, the description identifies the subject matter and mapping content well enough to know the tool's data scope. It does not describe the return format, but for a simple static reference this 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?

The tool has zero parameters and 100% schema description coverage, so the baseline score is 4. The description adds no parameter information, which is appropriate here.

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 resource (purchase and sales VAT codes) and the mapping it exposes (return boxes), so an agent can tell what data it returns. It does not explicitly contrast with vat_return, but the scope is still discernible.

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 use this tool versus vat_return or other siblings; the agent must infer it is a reference lookup. No exclusions or prerequisites 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?

With no annotations, the description carries the full burden; it does signal a read-style retrieval and tells the agent what fields come back, including the filed flag. It does not disclose the data source (sheet vs e-fatura), permissions, or what happens for a quarter that has not been created/indexed.

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 clause names a concrete piece of returned data. The phrasing 'as the sheet shows them' is slightly vague but does convey that values mirror the sheet layout.

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, so the description must describe return values — and it does, listing box 61, boxes 90-96, and filing status. What remains missing is the source of truth and the behavior for unfiled or non-existent quarters, which matters for a two-parameter lookup.

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 0%, so compensation is required. The description clarifies the quarter parameter domain (Q1-Q4) and ties it to a specific reporting period, but says nothing about the required 'year' parameter or its relationship to a year sheet.

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 — the Declaração Periódica boxes for a given quarter — and enumerates the contents (box 61 credit carried over, boxes 90-96 results, filed status). This clearly separates it from siblings like vat_codes (code lists) and mark_filed (mutation), though the retrieval verb is only implied by 'as the sheet shows them'.

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 call this versus alternatives such as vat_codes or mark_filed, and no prerequisites (e.g. whether the year must be indexed first). The agent must infer that this is the read path for a quarter's return.

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