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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds non-obvious behavior: raw JSON is returned, amounts come back as strings, invoice status "valid" actually means draft, and large responses are truncated to fit. Those are exactly the traits an agent cannot infer from annotations or schema.

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

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

The core verb and scope are front-loaded in the first clause, with the routing rule right behind it. The long parenthetical example list and embedded spec URL make it slightly dense, but each element carries usable 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 an open-world generic REST passthrough, it covers the essentials: scope, precedence, path format, the spec reference for unlisted endpoints, and known data quirks. An output schema exists, so return structure needn't be explained, though the truncation behavior could say how severe the cutoff is.

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

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

Schema description coverage is 100%, so the schema already documents both `path` (with an example) and `query` (with a page/per_page example). The description's only additions are alternative example paths and the /v1/ prefix constraint, which the schema also states — hence the baseline 3.

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

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

States a specific verb and resource ("Read-only GET of any UOL REST path") and immediately scopes it against siblings with "for data no other tool covers" plus concrete example endpoints. The only thing keeping it from a 5 is that the purpose is intrinsically generic — a catch-all escape hatch — rather than one well-defined resource.

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

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

Gives an explicit fallback rule ("Prefer the dedicated tools"), an explicit when-to-use condition ("data no other tool covers"), a list of representative paths, and a spec link for everything not covered. An agent can decide between this and the dedicated tools without further 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 context beyond the annotations by disclosing the side effect that a file is written to the server's filesystem and that the return value is a path. It does not cover overwrite behavior, target directory conventions, or failure modes. The filesystem write is a local side effect but does not meaningfully contradict readOnlyHint, which concerns the remote data store.

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

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

One sentence, front-loaded with the action and ending with what is returned. No filler or redundant restatement 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?

It is a simple one-parameter tool with an output schema, and the description explains both the action and the shape of the result, so there is little missing. The only notable gap is the absent guidance on document_id provenance and on filesystem target behavior.

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

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

Schema description coverage is 0%, so document_id is completely undocumented in the schema. The description only implies that the value refers to an uploaded document; it gives no format, source, or validity guidance to compensate for the coverage gap.

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: it "saves the original file of an uploaded document" and returns its path. That clearly separates it from get_uploaded_document and list_uploaded_documents, which deal in metadata rather than the file itself, though neither sibling is named 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 is implied rather than stated: the phrase "on the machine running uol-mcp" hints this is for when you need a local copy of the file. There is no explicit when-to-use, no mention of how it differs from get_uploaded_document, and no note about where a document_id can be obtained.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real context on top: the call writes a file to the machine running uol-mcp, a side effect not captured by readOnlyHint. It also discloses that ISDOC output is XML readable line by line and that the format is only available for confirmed issued invoices.

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

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

Three short sentences, front-loaded with the core action and file-write behavior, followed by the format variant and the eligibility restriction. 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?

With an output schema present, return-shape explanation is unnecessary, and the description covers the action, the format option, and the invoice-type restriction. A minor gap is any hint about where the saved file lands or how the caller learns the path, which is left entirely to the output schema.

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

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

Schema coverage is 50% — invoice_id is documented in the schema, format is not — but the description compensates by explaining what format=isdoc actually yields (Czech e-invoice XML, line-by-line readable) rather than just restating the enum. The default of pdf is only implied by the schema, not discussed.

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: 'Downloads an issued (sales) invoice rendered by UOL and saves it on the machine running uol-mcp,' plus the format=isdoc variant. This distinguishes export-to-file from metadata retrieval siblings like get_sales_invoice, though it never names that sibling 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?

Gives an explicit exclusion: 'ISDOC exists only for issued (confirmed) invoices' and 'Received invoices cannot be exported through the API,' which steers agents away from using it on purchase invoices. It stops short of naming an alternative tool for received invoices or explaining when PDF should be preferred over ISDOC.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add semantics — and it does, disclosing the snapshot/staleness model and the reporting obligation around as_of. That is exactly the kind of non-obvious behavior an agent would otherwise get wrong. It does not mention freshness lag beyond the monthly cadence or any account-visibility limits.

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

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

Two sentences, both load-bearing, with the resource definition front-loaded and the staleness caveat immediately after. No restatement of the name or title and no filler.

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

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

An output schema exists, so return values need no explanation, and the description covers the one thing that would cause misuse: treating snapshots as live balances. What is missing is positioning relative to the many sibling financial tools, which would help an agent choose correctly. Otherwise complete for a one-parameter read 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?

There is a single optional parameter and the schema documents it fully, including the default and the 120-snapshot cap. The description adds no additional meaning about what history does or when to request it, so the schema carries the load. Baseline 3 is appropriate given 100% schema description 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?

States a specific resource and its shape: the company's own bank accounts, broken out per account and summed per currency. That is far more informative than the title alone and distinguishes it from sibling overview tools by naming the granularity. It stops short of explicitly naming the sibling it replaces (e.g. get_financial_overview or get_business_snapshot).

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

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

Gives a concrete usage constraint that changes how the agent interprets results: the data is monthly opening-balance snapshots dated the 1st, not live balances, and the as_of date must always be quoted. It does not say when to prefer this over the other financial sibling tools, so no explicit exclusions are offered.

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 general read-only hints provided in annotations, the description provides vital behavioral context. It explicitly states how the tool handles partial data or failure, detailing that missing permissions result in null/error listings and how partial reads are flagged ('listed in incomplete').

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

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

The description is highly dense yet exceptionally well-structured. It begins with a compelling high-level hook, uses a comprehensive list to enumerate scope, and ends with actionable behavior instructions, maximizing information density per sentence.

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?

This tool is a complex aggregate, pulling data from many different categories (VAT, bank balances, receivables, documents). Because it has zero inputs, the description must account for its entire scope and behavior upon success or partial failure, which it does thoroughly.

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?

Since the input schema is empty (0 parameters), the description cannot add semantic meaning to inputs. Given the 100% schema description coverage and zero parameters, the baseline high score is appropriate.

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

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

The description clearly defines the tool as providing a consolidated, high-level summary of financial health ('How is the company doing?'). It explicitly lists the aggregated data points (revenue, VAT, receivables, etc.), distinguishing its function as an overview tool from the granular sibling tools provided.

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 definition provides clear guidance on its appropriate use by advising the agent to 'Use the dedicated tools for detail.' This sets an explicit boundary for when the agent should pivot to specialized functions rather than relying on this broad tool.

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, destructiveHint=false and openWorldHint=true, so the safety and side-effect profile is fully covered. The description adds that this doubles as a connection check, which is a useful behavioral note, but says nothing about caching, freshness of the VAT period data, or whether it fails when the tenant is unauthenticated.

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

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

Two sentences with no filler, and the returned fields are front-loaded ahead of the connectivity note. The opening is an elliptical noun fragment ('The accounting entity of this UOL tenant: ...') rather than a full clause, which is slightly less readable but not wasteful.

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 a published output schema, the description covers purpose, payload contents, and an extra use case, so nothing essential is missing. The only gap is the absence of any hint that the data is tenant-scoped and requires an authenticated connection, which the openWorldHint implies but does not state.

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 and the schema is empty, so there is no parameter meaning the description could add; baseline 4 applies for zero-param tools. The description does implicitly confirm no scoping input is needed (tenant is inferred), but that is incidental rather than deliberate parameter 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?

Names a specific resource — the tenant's accounting entity — and enumerates what it returns (name, IČO, DIČ, address, VAT filing period), so the agent immediately knows the payload. It is a noun phrase rather than an explicit verb, and it does not differentiate itself from siblings such as get_business_snapshot or get_financial_overview, but the resource is unambiguous.

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

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

The second sentence supplies a concrete secondary use case — verifying that uol-mcp connectivity works — which is genuine usage guidance. However, there are no conditions for when to prefer this over get_business_snapshot or get_financial_overview for tenant-level data, and no exclusions, so the routing guidance is only implied.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so safety is covered. The description adds what the response contains (addresses, bank accounts, default payment terms), which is useful payload context, but says nothing about lookup failure behavior for an unknown contact_id. Since an output schema exists, omitting return formatting is acceptable.

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 short, front-loaded sentence fragment with no filler. It is efficient, though the fragment form leaves the action unstated rather than making the sentence tighter.

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

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

For a single-parameter read tool with an output schema and full annotation coverage, most of the agent's needs are met by structured fields. The description covers payload scope but not the retrieval verb or fallback behavior when no contact matches.

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

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

Schema description coverage is 100% and the single required contact_id is documented with sourcing hints, so the schema does the heavy lifting. The description adds only the implicit signal that contact_id resolves to exactly one record. 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 is a noun phrase naming the resource and its payload ('One contact with all addresses, bank accounts and default payment terms') rather than a verb+resource statement, so retrieval must be inferred from the tool name. It does implicitly differentiate from the list-oriented sibling search_contacts by saying 'One contact', but never states that 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?

There is no guidance on when to call this versus search_contacts or the invoice tools, and no mention of what contact_id source to prefer. The only hint is inside the schema ('e.g. from search_contacts or an invoice'), not the description.

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 readOnly/idempotent annotations, the description discloses genuinely non-obvious traits: amounts are net of VAT and in home currency, the current month is still running, unbooked months return booked=false, and the response includes the largest revenue and expense accounts with names. It does not cover cost or latency for a ledger-wide aggregation, but the semantic caveats an agent needs to avoid misreporting are all present.

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

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

Two dense sentences, front-loaded with the scope before the caveats, and the Czech/class-6/class-5 parenthetical earns its place by anchoring the ledger mapping. The 'same basis as the UOL web dashboard' clause is slightly indirect but pays off by ruling out the invoice-only interpretation. Minor tightening possible, but nothing is padding.

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

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

An output schema exists, so return values need not be explained, and the description instead spends its budget on the traps: running current month, booked=false, net-of-VAT amounts, home currency. For a single-optional-parameter read tool with full annotation coverage, nothing an agent needs in order to call it and report results honestly is missing.

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

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

Schema coverage is 100% and the single parameter 'months' already documents 'Months ending with the current one' with defaults and bounds. The description reinforces that figures are 'per month' and that the current month is partial, but adds no new meaning about the months parameter itself (e.g., no note that the window also drives the top-accounts summary, though that is inferable).

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

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

States a specific resource set (revenue, expenses, profit per month) drawn from a named source (the general ledger) and explicitly pins the accounting basis: 'the same basis as the UOL web dashboard, so payroll, rent and other internal documents count, not just invoices.' That basis statement is what separates it from invoice-centric siblings like get_sales_invoice or list_receivables, so an agent can route correctly without opening the schema.

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

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

There is no explicit when-to-use or when-not-to-use guidance relative to siblings such as get_vat_overview or get_business_snapshot, which plausibly overlap. What exists instead is interpretive guidance — 'say so instead of reporting zero' for unbooked months — which is valuable but governs reading the output, not selecting the tool. Usage is strongly implied by the scope sentence 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and idempotency profile needs no restating. The description does add useful content about what the response holds (line items, VAT, payment symbols), but it says nothing about not-found behavior, error cases, or what the openWorld flag means for external data freshness.

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 short line with no filler and the scope qualifier front-loaded. It is slightly under-specified as a sentence fragment rather than a statement of what the tool does, but nothing is wasted.

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

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

The tool is simple, carries rich annotations, has a fully described schema and an output schema, so the description does not need to explain returns in depth. It could have stated the retrieval-in-by-ID semantics and pointed at search_purchase_invoices, but almost everything an agent needs sits in structured fields.

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 at 100% schema description coverage, so the schema already carries the meaning and even names the producing tool. The description adds nothing about the ID's format or source, which is the correct baseline for a fully documented one-parameter schema.

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

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

It names a specific resource, a received (purchase) invoice, and enumerates what comes back (line items, VAT, payment symbols), which cleanly separates it from the sibling get_sales_invoice. The only weakness is the absence of an explicit verb, since the fragment reads as an object rather than an action.

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 supplies no guidance on when to call this or when to call search_purchase_invoices instead, nor any prerequisite such as needing the ID first. The workflow hint only appears in the schema as 'invoice_id from search_purchase_invoices', so the agent has to infer the lookup pattern from structured fields rather than the description.

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 open-world, so the safety profile is handled. The description adds real behavioral context beyond them: the response payload composition (line items, VAT, payment symbols, bank account, payments received) and the downstream workflow it supports. It is silent on error behavior or cross-company scoping, which keeps it from a 5.

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

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

Two sentences, payload description front-loaded, then alternative-tool routing followed by the practical template use case. 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?

With an output schema present and rich annotations, the description only needs to cover purpose, differentiation and when to reach for it - all of which it does. Minor omission: it does not say whether the lookup is scoped to the authenticated company or what happens for an unknown id.

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

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

There is a single parameter with 100% schema description coverage, and the schema itself notes the id comes from search_sales_invoices. The description adds no further meaning about invoice_id, so the baseline of 3 applies.

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

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

The description names a specific resource (one issued sales invoice) and enumerates exactly what it carries: line items, VAT, payment symbols, own bank account and payments received. It also explicitly separates itself from export_sales_invoice, so an agent can distinguish it from the nearest sibling without inspecting the schema.

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

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

It explicitly routes the PDF/ISDOC case to export_sales_invoice and states a concrete use case: review earlier invoices to the same buyer as a template for issuing a new one. It does not name search_sales_invoices as the way to obtain the id, but the input schema covers that link.

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=false, so the safety profile needs no restating. The description does add one genuinely useful behavioral note — that pairings reference records by type and internal gid rather than invoice number — which steers the agent away from expecting a human-readable invoice identifier. It says nothing about behavior for unknown or deleted document ids, which is the remaining gap.

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

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

Two sentences, front-loaded with what is returned, with no filler. The second sentence is a caveat that earns its place, though the opening is a bare noun phrase rather than a verb-led statement of action.

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

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

For a single-parameter read tool with an output schema and full safety annotations, most of the burden is already carried by structured fields, so the description is nearly sufficient. What remains missing is where document_id comes from and what happens on a miss — details an agent needs to invoke this correctly on the first try.

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 document_id, so it adds no meaning beyond the bare string type in the schema. An agent must guess the expected format (internal id, UUID, file key) and whether the id comes from list_uploaded_documents.

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 and enumerates what it carries: original file name, tags, and paired bookkeeping records. The lead phrase "One uploaded document" distinguishes it from the plural sibling list_uploaded_documents, though it never states the retrieval verb explicitly and does not call out download_uploaded_document as the byte-returning alternative.

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 reach for this tool versus list_uploaded_documents or download_uploaded_document, and no prerequisites or error conditions are mentioned. The only implicit usage signal is the singular "One uploaded document," which the agent must infer.

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, but the description adds substantive behavior: closed periods come from UOL's exact DPH closing document while open periods are estimates computed with stated rules (output VAT by DUZP, input VAT by later of DUZP and receipt date). It also discloses what is excluded (proformas skipped, corrective invoices as credit notes, internal documents and reverse charge omitted), which is exactly the accuracy caveat an agent needs.

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

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

Front-loaded with the resource and returned values before the caveats, and each clause carries real information (estimation rules, exclusions). The second sentence is a long run-on with semicolons, but trimming it would lose material accuracy caveats.

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 reporting tool with an output schema and fully documented parameters, the definition covers derivation, accuracy, ordering and exclusions well. It is slightly silent on scope (which company/workspace the figures belong to and how far back the periods extend), but that is minor given the surrounding 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?

Schema coverage is 100% and the single `periods` parameter already documents its 1-12 range and the 4/2 default per payer type. The description mentions monthly/quarterly periods only as a company-settings fact, not as parameter meaning, so it adds nothing beyond the schema — the baseline 3 applies.

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

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

The description names the resource precisely (VAT/DPH per filing period) and enumerates the returned figures: output VAT, input VAT, amount to pay or excess deduction, due date, plus the sort order (newest first). No sibling tool covers VAT, so an agent can identify this tool from the description alone.

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?

Implicit usage: an agent learns the filing period (monthly/quarterly) is taken from company settings rather than passed as a parameter, which is useful routing context. However, there is no explicit when-to-use statement and no pointer to alternatives such as get_financial_overview for a broader picture, so guidance stays 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds one genuinely useful behavioral detail: records come back 'as UOL sends them, minus audit fields', which tells the agent the response shape is a stripped passthrough. It says nothing about ordering, caching, or size characteristics of the upstream source.

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?

Purpose is front-loaded in the first clause and the response-shape caveat is isolated in a short second sentence. The long enumerated list is somewhat run-on and partly duplicates the enum, but the glosses make the repetition earn its place. No filler or marketing language.

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

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

With an output schema present and a simple three-parameter surface, the description covers what the agent needs: what the tool returns, that audit fields are stripped, and why each kind matters. The only gap is that it does not indicate whether results are paginated further or how to locate a specific record by ID, which a sibling lookup tool might handle.

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 67%, and the uncovered parameter is the critical 'kind' enum. The description compensates well by glossing each value, including Czech operational terms (střediska, zakázky, pokladny) and the practical note that 'products' supplies the product_id needed by invoice lines. Page/limit semantics are already documented in the schema, so no further detail is required 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 opens with a specific verb-plus-resource framing ('Reference data (číselníky) used by invoices and documents') and enumerates the exact kinds of reference data the tool returns. An agent can immediately tell this is a catalog/lookup tool. It does not name a sibling, but no sibling in the list overlaps with this function, so differentiation is less critical.

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: the parenthetical '(the product_id invoice lines need)' hints at the key downstream use case of fetching product IDs before building invoice lines. There is no explicit when-to-use versus when-not-to-use guidance and no mention of alternatives for looking up a single record.

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 open-world, so the safety bar is largely met. The description goes beyond them by disclosing a real data limitation (the UOL API exposes no payment status for received/purchase invoices) and the default ordering (most overdue first), both of which affect how results may be interpreted. It does not discuss pagination or truncation behavior, though the schema's limit description partly covers that.

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 resource and return shape before the usage questions and the scope caveat. The Czech term "pohledávky" is domain flavor that earns little for an agent, but it costs only a clause.

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

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

With an output schema present, the definition needn't explain return values, and annotations cover the safety profile; the description supplies the remaining essentials — scope limits and default ordering. The main residual gap is guidance on when this beats search_sales_invoices for overlapping invoice-level queries.

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 high (78%) and enums are self-explanatory, so the schema carries most parameter meaning. The description only echoes the default sort ("most overdue first by default") and does not clarify interactions such as how state, overdue_only and the date ranges combine. That is baseline-level added value.

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 and result shape: "Receivables of issued (sales) invoices — totals per currency plus the matching invoices," plus a default ordering. It also bounds the resource (sales invoices only, no purchase-invoice payment status). It stops short of explicitly contrasting with the sibling search_sales_invoices, which an agent must still disambiguate on its own.

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?

Concrete triggering questions ("who owes me money", "what is overdue", "has customer X paid") give the agent clear contexts to reach for this tool, and the closing sentence is an explicit when-not for purchase invoices. There is no explicit routing to alternatives such as search_sales_invoices or get_financial_overview for the overlapping receivable-total case.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful behavior beyond that: results are returned newest first and the state field reflects the accountant's processing workflow. It says nothing about pagination behavior, result volume, or what happens with empty filters.

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

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

Two compact sentences with no filler, front-loading what the resource is and its ordering before the filter hint. The Czech term in parentheses is minor clutter but serves disambiguation for a domain-specific resource.

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 annotations cover the safety profile. For a five-optional-parameter list tool the description covers identity, ordering and the most important filter; only sibling routing and the remaining filter semantics are left implicit.

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

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

Schema description coverage is 80%, so the schema already documents page, limit, created_from and created_to, and the enum values are supplied. The description adds meaning only for state=unprocessed, leaving processed/error and the date filters to the schema. Baseline 3 is appropriate when the schema does most of the work.

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

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

States a specific verb and resource ('Documents uploaded to UOL for the accountant'), plus the concrete content types (receipts, received invoices as PDF/images) and the sort order (newest first). It does not explicitly distinguish itself from siblings like get_uploaded_document or download_uploaded_document, though the list-vs-get contrast is implied by the name.

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

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

Provides one concrete usage cue — 'state=unprocessed lists what the accountant has not processed yet' — which tells the agent when that filter matters. It gives no guidance on when to pick this over get_uploaded_document/download_uploaded_document, nor any prerequisites, so usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds that results are contact_id values usable as filters elsewhere, which is useful context, but it says nothing about pagination defaults, hidden contacts, or result volume.

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 zero waste; the resource and searchable fields come first and the downstream use of contact_id follows. Nothing is padded or 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?

With nine optional parameters and an output schema present, the definition is largely complete: return values need not be explained, and the contact_id note is a bonus. The one gap is the absence of any statement about default behavior when no filters are supplied.

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 89%, so the schema already explains nearly every parameter, including the IČO and DIČ mapping. The description's mention of name/IČO/DIČ mostly restates that, adding no syntax or precedence guidance (e.g. name vs query).

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 ('Search customers and suppliers') plus the searchable identifiers (name, IČO, DIČ), so the agent knows exactly what the tool does. It does not explicitly distinguish itself from the sibling get_contact, which retrieves a single contact, leaving that routing to inference.

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

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

The sentence 'Returns contact_id values for the invoice and receivable filters' implies a clear usage context: call this to obtain IDs needed by invoice/receivable tools. However, it never states when not to use it, what happens with zero parameters, or how it relates to get_contact for single-record lookups.

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, non-destructive and openWorld, so safety is covered. The description adds two pieces of non-obvious behavioral context the annotations cannot convey: the API silently ignores issue-date filters on this endpoint, and the UOL API exposes no payment status for purchase invoices, which warns the agent away from an unavailable filter or expected field.

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 resource identification followed by the two constraints that matter before calling. The Czech gloss and the filter caveat each earn their place; nothing is redundant, though the phrasing is slightly terse for a 16-parameter tool.

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

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

For a 16-parameter, all-optional search tool with an output schema present, the description covers what structured fields cannot: the identity of the resource, which date filters actually work, and a data limitation (no payment status). Pagination, formats and limits are already documented in the schema, so nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 75%, so the schema already documents most parameters, but several date fields (tax_date_from/to, received_date_from/to, due_date_from/to) exist with identical YYYY-MM-DD descriptions and no differentiation. The description resolves that ambiguity by naming tax_date_* as DUZP and marking it and received_date_* as the working date filters, which is real added meaning beyond the schema.

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

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

The description states a specific verb and resource ('Search received (purchase) invoices') plus the Czech equivalent 'přijaté faktury', which unambiguously separates it from sibling search_sales_invoices and get_purchase_invoice. An agent can tell it is a filtered list operation on the received-invoice resource without opening the schema.

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

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

It gives one concrete usage rule — because UOL ignores issue-date filters on this endpoint, filter by tax_date_* (DUZP) or received_date_* instead — which is genuinely actionable. However, it never says when to pick this over get_purchase_invoice (single-record lookup) or search_sales_invoices (direction), and gives no exclusions or prerequisites, so the routing guidance is only partial.

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 (which already declare readOnly/idempotent/non-destructive), the description discloses default sort order, that each row carries payment status derived from UOL receivables, and that drafts and cancelled invoices are included so callers must check status. That inclusion caveat is exactly the kind of non-obvious behavior an agent needs and cannot get from the schema or hints.

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

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

Four compact sentences, front-loaded with the core identity and ordering, then the date semantics, then the completeness caveat, then the alternative routing. No filler or restatement 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?

For a 15-parameter search tool with rich annotations and an output schema, the description covers the decision-relevant semantics: what is searched, ordering, result completeness, and sibling routing. The enum meaning of type (corrective/proforma/penalty) and amount filters are left to the schema, a minor residual gap.

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

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

Schema coverage is 80%, so the baseline is 3; the description earns a bump by disambiguating the three date families (tax/issue/due) that the schema only labels as "Date as YYYY-MM-DD". It leaves other parameters such as type enum values and variable_symbol unelaborated, but the highest-risk ambiguity is resolved.

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 ("Search issued (sales) invoices"), gives the Czech alias "vydané faktury", and notes the default ordering (newest first). It is clearly separable from siblings search_purchase_invoices and list_receivables, the latter of which is named 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?

Gives explicit routing rules: use tax_date_* (DUZP) for accounting-period questions versus issue_date_* for "issued in", and defer to list_receivables for "who owes me money". Both when-to-use and when-to-use-something-else are stated.

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