Zeno

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

With zero annotations the description carries the full burden and does so richly: the held → posted state flip, 409 on repeat accept, 409/422 for closed period, sealed year and unknown account, the 403 authorization split between human and agent, and the accepted_by_kind audit field (mcp over MCP). Nothing about safety or side effects is left to guess.

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 action, then error codes, then body variants — a sensible order where every sentence carries information. RST-style double-backtick markup and telegraphic fragments ('and ``needs_split_source`` a ``reclassify_from_account_code``') make it denser to parse than necessary.

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?

A conditional-body mutation tool with no annotations and no output schema, and the description covers the correctness-critical pieces: authorization, failure modes, state transition and per-kind body requirements. What it omits is the success response shape and the meaning of the remaining body flags, which an agent would have to infer.

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

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

Schema coverage is 0%, so the description must compensate, and it does for the hardest part: body requirements are spelled out per hold kind — expense:receipt:item: needs employee_id + category_id, autopost:capitalize: needs fixed_asset_category_id when absent and needs_split_source needs reclassify_from_account_code. It leaves separate_document, useful_life_months and confirm_not_card_statement undocumented, so the conditional `body` object is only partially covered.

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 ('accept of a held decision') plus the concrete effect — 'posts the AI's proposal' — so an agent knows exactly what changes. The 'held' qualifier and the sibling list_autopost_decisions make the boundary obvious without opening a 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?

Gives strong when-it-works / when-it-fails guidance: a person's accept overrides guardrails, an agent's is refused (403) unless the row is agent_acceptable or an expense receipt. It does not name an alternative tool to use when the row is not agent-acceptable, so the fallback path is left implicit.

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 discloses one important trait — the result and any error are identical to a direct call — but says nothing about whether the invoked operation may be destructive, whether it needs specific permissions, or whether it is idempotent, all of which matter for a generic 'run anything' 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 tight sentences, front-loaded with the core action and each subsequent sentence adding distinct value: parameter sourcing, then return/error equivalence. 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?

With no output schema or annotations and a low-coverage schema, the description supplies the missing sourcing guidance and return behavior, and defers detail to describe_operations. The notable gap is the absence of any warning that dispatched operations may mutate data.

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, and it does: it explains that `name` is an operation name sourced from find_operations and that `arguments` is the object described by describe_operations, including the null/omitted case. It does not give a concrete format example, but the origin and structure of both parameters are covered.

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: 'Run any operation by name', and clarifies scope by noting it covers both listed and unlisted operations. It distinguishes itself from siblings by tying directly into the find_operations/describe_operations workflow, though the dispatcher framing could be sharper.

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 clear context for use: name comes from find_operations, arguments from describe_operations, and there is an explicit rule to omit arguments for zero-arg operations. It stops short of an exclusion rule (e.g. when to call a listed sibling tool directly instead of routing through this dispatcher).

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 so: it discloses that pending is deliberately not an error because errors read as 'do not retry', that collected means idempotently nothing new was issued, that api_key must be installed via the accompanying note before it works, and that scope governs reach. It also surfaces the rate-limit-becomes-throttled behavior and the longer poll interval.

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 purpose and organized as a scannable status list, which is the right shape for a state machine. It is dense but mostly earns its length, with only mild repetition in the denied/expired branches about refusals turning into repeated prompts.

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 define the return contract, and it does thoroughly: the full status enum, the presence of api_key, note, scope, company_id, throttled, and poll_interval_seconds. What is missing is the provenance of claim_token and any stated default for poll_interval_seconds.

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 single input parameter, claim_token, has 0% schema description coverage and is never mentioned in the description — its origin and format are unexplained. The description details output fields (status, api_key, note, scope, company_id, throttled, poll_interval_seconds) but that does not compensate for the undocumented required input.

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 ('Collect the key') plus the precondition ('once the user has approved'), so an agent knows this is the polling/retrieval half of the key flow. It references request_api_key, start_signup, and onboarding_guide in the status branches, giving implicit sibling differentiation, but the opening sentence alone does not explicitly distinguish this tool from the two ways a claim is created.

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 explicit when-to-call guidance (only after approval), a per-status action map, named alternatives, and explicit prohibitions ('denied — stop', 'do not simply open another one'). The retry protocol, including the throttle backoff, is spelled out rather than left to 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?

No annotations are provided, so the description carries the full burden and does so richly: a draft changes no ledger balance, gets no invoice number, appears in no VAT return; the accountant role is required; totals/VAT/discounts are computed server-side and must not be sent; issuing is a separate call. This is the behavioral context an agent needs 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?

Front-loads the single most important fact (this creates a DRAFT, nothing is booked), then organizes the body parameters, then the return value and the readiness check. Every sentence carries new information; nothing is redundant.

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

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

For an 18-parameter mutation tool with no annotations and no output schema, the definition covers the draft semantics, required fields, key body fields, server-side computation, and the return shape ('created invoice with its lines and computed totals'). It falls short only on the secondary draft fields, which an agent may still have to infer from schema alone.

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?

With 18 parameters and 0% schema description coverage, the description compensates well for the tricky ones: issue_date and counterparty_id requirements, currency/language, due_date defaulting from payment terms, doc_type semantics, line quantity/unit_price/account_code/vat_code_id, and the 'do not send totals' rule. However, roughly half the schema is unexplained (payment_terms_id, issuer_profile_id, credited_invoice_id, service periods, invoice/line discount kinds and values, legal/footer/notes text).

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

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

States a specific verb+resource+lifecycle state: 'Create an outgoing (sales) invoice as a draft.' It clearly distinguishes itself from the sibling issue_ar_invoice by naming the later posting step, so an agent can route correctly without opening either schema.

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

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

Explicitly says when to use it (draft exists so it can be edited; posting happens later at POST …/ar/invoices/{invoice_id}/issue) and when NOT to use it for credit notes (a credit_note draft can never be issued — use POST …/credit-note instead). Names alternatives and the conditions that select them.

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 carries the full burden and does so: it states the entry is a draft, that it does not touch the books until …/post, that source_ref_type/source_ref_id are defaulted by pipeline paths only, that document_id is the retrofit attach (also available post-creation on a posted entry), and that auto_reverse_date must be after posting_date (422 otherwise) and can only be set while draft. That is exactly the mutation/permission/reversibility context 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?

Long but front-loaded with the crucial 'draft / no source document' fact, then the routing alternatives, then the auto_reverse constraint. The bulleted sibling routing is dense and earns its space, though the prose around the document attach paths is slightly repetitive.

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 9-param mutation tool with no annotations and no output schema, the description covers creation semantics, draft/post lifecycle, evidence attachment, and auto-reversal well. It stops short of explaining the line structure (line_role semantics, amount_base vs amount_currency, open_item behavior beyond the schema snippet), leaving a gap for the core booking payload.

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% at the top level, so the description must compensate; it thoroughly explains document_id and auto_reverse_date (constraints, timing, 422), but leaves entry_type (13-value enum), line_role (16-value enum), the lines array shape, currency, period_id, company_id, and description field unexplained. Partial compensation for a 9-parameter tool.

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

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

States a specific verb + resource (create a *draft* journal entry by hand) and immediately nails the distinguishing trait: no source document unless one is named. This lets an agent separate it from post_gl_journal_entry and the ingestion/coding siblings without opening a 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?

Explicit when-to-use (reclassifications, provisions, accruals, year-end adjustments) and when-not ('Do not transcribe a document into it and then attach the file'), then routes each document-backed case to the correct sibling endpoint (uploads/intake → autopost-decisions, items/{id}/coding, bank-entries/manual-coding, opening-entries). Nothing is left to 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?

With no annotations, the description carries the full burden. It discloses the key behavioral trait that `as_of` reconstructs historically-open items so results agree with a historical aging report, and it implies a read operation. But it omits auth/permission requirements, pagination, and confirmation that the operation is non-mutating.

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 passages with the core identity front-loaded and the `as_of` nuance following. Efficient, though the heavy backtick/typographic formatting adds noise without adding meaning.

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 tool with no output schema and no annotations, the description conveys what comes back ('open items + totals') and the `as_of` semantics. It stops short of describing the totals' composition, result shape, or limits, leaving modest gaps for a financial drill-down tool.

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

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

Schema description coverage is 0%, so compensation is required. The description explains the one non-obvious parameter, `as_of`, in real depth (historical reconstruction semantics, parity with the aging endpoint), but leaves `company_id` and `counterparty_id` purely reliant on self-explanatory names.

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 resource and scope: 'One customer's open items + totals', and frames it as 'the aging row's drill-down', which lets an agent distinguish it from broader statement/report siblings. It is a noun phrase rather than a verb+resource, but the returned content 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 parenthetical 'the aging row's drill-down' implies when to reach for it (drilling into a customer's aging row), which is useful contextual usage guidance. However, it names no alternative sibling and no explicit when-not condition, so the routing signal remains implicit.

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 well: it discloses the return contents (description + JSON-Schema arguments), the effect of include_output_schema, the 10-operations-per-call cap, and that overflow is surfaced in 'omitted' rather than dropped. It does not state auth requirements or explicitly that the call is read-only, but the retrieval framing makes the safety profile self-evident.

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 action is front-loaded in the first sentence, and the limit/omitted behavior closes cleanly. The middle paragraph on include_output_schema is somewhat verbose, with an opinionated parenthetical about payload composition, but it remains informative rather than 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?

There is no output schema, yet the description explains what comes back (description, arguments, or result shape when requested, plus 'omitted'). Combined with the disclosed batch limit, this is nearly complete for a discovery meta-tool; only auth and error behavior are unaddressed.

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 gives meaningful semantics for include_output_schema (the only route to a result shape, and when to request it) but leaves 'names' to inference — the reader must deduce these are operation identifiers from find_operations. Half the parameters are covered, half are not.

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 first sentence states a specific verb and resource ('Get the full argument schema for operations') and scopes it to operations 'found via find_operations'. It clearly differentiates itself from the sibling find_operations (which lists) and from call_operation (which invokes), so an agent can route correctly without opening any schema.

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

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

It gives explicit guidance for the optional parameter ('Ask for it when you must know the shape in advance... usually you do not') and ties its use to find_operations as the discovery prerequisite. It stops short of stating when NOT to use this tool (e.g., when the operation is already a listed tool) and doesn't address error/auth preconditions.

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, and it discloses nothing: no read/write nature, no data source, no rate limits, no return shape. It is a bare label rather than a behavioral statement.

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 words with no front-loaded information at all; this is under-specification rather than conciseness. There is nothing for an agent to act on.

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

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

With no annotations, no output schema, an undocumented required parameter, and 47 similarly named siblings, the description is nowhere near complete enough to invoke the tool correctly.

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

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

Schema description coverage is 0% and the single required parameter entry_id has no description in either the schema or the tool description. The description does not even acknowledge that a parameter exists or what identifier it expects.

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?

"Entry Candidates" merely restates the tool name and supplies no verb, object, or outcome. An agent cannot tell whether this lists, computes, ranks, or filters candidates, nor what an "entry" is in this domain.

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?

No when-to-use guidance, no prerequisites, and no mention of any of the 47 sibling tools such as settle_entry, get_bank_entry, or list_gl_journal_entries that an agent would need to disambiguate against.

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 so generously: it discloses the scoring model (all words must match, matching all doubles the score, extra words widen rather than narrow, name matches outweigh description matches), the 100-item cap, deterministic/stable paging, and a startup-fixed registry so no operation is dropped or duplicated across pages. These are exactly the non-obvious behaviors an agent needs to query well.

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 single most important fact (unlisted operations exist) and organized by invocation mode. It loses a point for the changelog aside ('the AND-then-fall-back-to-OR behaviour this said before was removed in ef47aa9ab'), a commit hash that costs attention and gives an agent nothing actionable.

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 exist, so the description must stand alone, and it mostly does: it explains what browsing/tag/query return (areas with operation counts, ranked matches) and how to page through large result sets. It could say a bit more about the shape of a returned match (name, description, tag) before handing off to describe_operations, but the workflow is complete enough to call correctly.

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

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

Schema description coverage is 0%, so the description must compensate, and it defines all four parameters semantically: tag lists one area, query searches by keyword, limit is capped at 100, and offset is driven by next_offset for paging. It stops short of stating the defaults (25/0/empty string) and whether tag and query can be combined, but the gap is minor.

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

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

Opens with a specific verb and resource ('Search EVERY operation this server offers') and immediately carves out the scope that makes it unique: operations not present in the visible tool list. It names concrete examples (payroll, VAT returns, year-end close) and distinguishes itself from describe_operations/call_operation by pointing to them as the follow-on steps.

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?

Prescribes exactly when to use it ('Search here before concluding that Zeno cannot do something') and enumerates the three invocation modes: no arguments to browse tags, tag to list one area, query for keyword search. It also routes the agent onward via describe_operations then call_operation, giving a complete decision path with no inference required.

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, and it does much of that work: it declares the read nature ('CompanyMember read'), the status lifecycle draft→issued→cancelled, that document_no is null on a draft, and that payment_status/open_amount are derived from the linked open item. It omits what happens on a nonexistent or cross-company invoice_id (error vs empty), which a mutation-free read tool could still usefully state.

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 its arm, then the payload, then the routing caveat. It is longer than typical, but with no output schema the field enumeration (net/vat/gross, document numbers, snapshot ids) is load-bearing rather than padding; only the parenthetical field lists feel slightly over-stuffed.

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

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

With no annotations and no output schema, the description is the only place an agent can learn the return shape, and it covers header, line amounts, totals, lifecycle states, document linkage and derived payment fields, plus scope exclusions. Nothing an agent needs 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?

Two required parameters with 0% schema description coverage, so the schema adds nothing. company_id and invoice_id are largely self-evident from their names and the 'CompanyMember read' hint, but the description never explains the tenancy/scoping relationship between them or the accepted id format. Adequate, not additive.

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 scope: a single authored outgoing AR invoice with its lines, plus the exact payload it carries (header, lines with computed amounts, totals, lifecycle). It explicitly distinguishes itself from the ingested 'item' arm and from list_ar_invoices / get_item siblings, so an agent can pick it without opening a 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?

Gives a clear when-not rule ('a receivable that arrived as an ingested document is an item, not an ar_invoice') and routes follow-up needs (journal entry, settling bank transactions, credit-note chain) to the related endpoint. It does not mention how to obtain the invoice_id (e.g. via list_ar_invoices), so the routing story is strong but not fully closed.

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, and it discloses almost nothing. "Get" weakly implies a read, but there is no statement about permissions, error behavior for an unknown entry_id, or idempotency — all of which matter for a financial-record lookup.

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 short, but this is under-specification rather than conciseness; four words convey no information beyond the tool name. Brevity here costs the agent everything it needs to call the tool correctly.

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 financial-record retrieval tool in a 49-tool family with no annotations, no output schema, and no parameter documentation, the description is completely inadequate. Nothing tells the agent what it gets back or how the returned entry should be interpreted.

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 single required parameter entry_id has no variability expectation. The description adds no meaning beyond the parameter's self-evident name, and it does not clarify whether entry_id is an internal ID, a bank reference, or a composite key.

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?

"Get Bank Entry" is a near-tautology that restates the tool name without adding scope, and it does not distinguish itself from siblings like get_bank_status, list_bank_entries, entry_candidates, or get_gl_journal_entry. An agent learns only that some bank-entry object is fetched, not what form or by what key.

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

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

There is no when-to-use guidance, no exclusions, and no pointer to an alternative tool. In a family containing list_bank_entries, entry_candidates, and settle_entry, the agent has no basis for choosing this tool over those.

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 so richly: it declares "Read-only", documents the 403 on non-member company_id, explains gap semantics (merged coverage windows, internal holes reported, ZCT-509), and discloses the 10/account cap on period_gaps with an exact period_gap_count. It also clarifies that "Reconciled" means matched entries, not ledger=balance, and that non-zero suspense blocks a clean VAT close.

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 purpose and the primary clarification (what "Reconciled" means) are front-loaded before the endpoint comparisons and gap mechanics. It is dense and cross-reference heavy, but most sentences earn their place given the composed behavior; slightly long for a status 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?

With no output schema and no annotations, the description still conveys the return surface (per-account entry-status counts, in_suspense counts, latest closing balance, company-level GL Suspense balance) plus the caveats that matter for correct interpretation. Nothing essential for calling or interpreting it 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 description coverage is 0% for the single company_id parameter, so the description must compensate. It adds meaningful semantics: the parameter is a CompanyMember identifier, and an explicit non-member company_id yields 403. This is real added meaning, though format details remain implicit.

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 composed resource ("Composed bank snapshot") and frames it with a concrete question ("is my banking up to date?"). It explicitly distinguishes itself from siblings by naming the three endpoints it replaces (bank-accounts, coverage, reconciliation/summary) and calls out what those still cannot answer.

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

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

It states when to use this tool (one call for bank snapshotting) versus alternatives ("use …/reconciliation/completeness per month"), and notes it is not period-scoped. It even enumerates the gaps the three substitute endpoints would leave, leaving nothing to 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?

No annotations are provided, so the description carries the full burden. It does disclose the auth mode ('jwt, scoped') and two concrete failure modes (403 for non-member non-admin, 404 if absent), which is real behavioral value, but it leaves 'scoped' undefined and says nothing about what data comes back or rate-limit behavior.

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

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

Two short, front-loaded sentences with zero filler; the core action comes first and the failure modes follow compactly.

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

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

For a simple single-param read this covers the essentials (identity, auth, error semantics), but with no output schema the description should at least hint at the returned company shape or the meaning of 'scoped'.

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% for the single required company_id, and the description adds no format, source, or lookup hint for it. An agent gets no help beyond the parameter name.

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 ('Get one company'), and the phrase 'one company' implicitly contrasts with the sibling list_companies. It does not name the alternative explicitly, but the singular 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?

The description gives error conditions (403/404) but no guidance on when to call this versus list_companies or global_search, nor any prerequisite about already knowing a company_id. Usage is only inferable from the name.

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

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

No annotations are provided, so the description carries the full burden, and it does substantial work: read-only, 422 on out-of-FY month, 403 on non-member company_id, problem reporting (unbalanced trial balance, unclassified accounts, year-not-opened, mixed currency), balance sheet cumulative vs P&L cash-flow monthly, and the exact inclusion rule ('posting_date' inside the gl_fiscal_year window, surfaced via fiscal_year_cut). It stops short of describing pagination or response size, but behavioral disclosure is far above the norm for an un-annotated 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?

The content is valuable but the layout is heavy: bolded mid-sentence fragments, a paragraph on 'The cut' and a cross-reference to ZET-166 read like internal release notes rather than agent-facing guidance. The critical routing and parameter facts are front-loaded, but the section is longer than its task requires.

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 computed multi-statement report with no output schema, the description covers selection rules, defaults, error conditions (403/422), scoping semantics, and the aggregation cut rule. Nothing an agent needs to call it correctly or interpret the result boundaries 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 description coverage is 0%, so the description must compensate, and it does: fiscal_year optional-by-default semantics, month's YYYY-MM format and inside-the-FY constraint with the 422 consequence, and the balance-sheet-cumulative vs P&L-monthly behavior month triggers. This is meaning the schema cannot express.

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

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

Opens with a specific verb+resource+scope ('Computed balance sheet + P&L for a fiscal year, from the journal') and explicitly distinguishes itself from snapshots and from the /gl/reports/* family that cuts by a stamped fiscal_year_id. An agent can separate it from gl_balance_sheet, gl_profit_and_loss, and gl_trial_balance without opening schemas.

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 clear context: fiscal_year optional defaults to latest FY with journal data, month narrows to one month with a 422 otherwise, non-member company_id returns 403, and it explicitly says it is distinct from the balance-sheet snapshot endpoint. It lacks a direct 'use this instead of X when Y' routing sentence against the computed siblings (gl_balance_sheet, gl_profit_and_loss), but the snapshot/report contrast covers the main ambiguity.

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 so substantively: it discloses that reversed entries are included (both legs), drafts excluded, that the server carries running balance across pages, and the distinct semantics of page_opening_balance vs closing_balance/total_debit/total_credit. It omits any permission/auth or rate-limit note, so not a full 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?

Front-loaded with the core purpose, then the important exclusions and balance semantics. Dense but nearly every clause earns its place; the field-naming detail is slightly heavy but justified by the absent output 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?

With no annotations and no output schema, the description steps up by explaining return-field semantics, paging continuity, and 404/422 error conditions. Only the undocumented limit/offset behavior and any auth prerequisites keep it from being fully 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 description coverage is 0%, so the description must compensate. It adds real meaning for account_id (FY-scoping) and date_from/date_to (422 when from > to), but says nothing about limit, offset, or company_id, leaving half the parameters undocumented in both schema and prose.

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 ('One account's ledger (Kontoauszug)') and the exact content it returns ('every booking that touched it, in date order, with Soll/Haben and the running balance'). This is clearly distinguishable from siblings like list_gl_journal_entries or gl_trial_balance.

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?

Explains the selecting context well: account_id already fixes the fiscal year so no FY parameter is needed, posted AND reversed entries are included while drafts are not. It does not, however, explicitly name an alternative sibling tool or state when to prefer this over list_gl_journal_entries, leaving that to 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?

With no annotations, the description carries the full behavioral burden and does disclose genuinely non-obvious traits: drafts return empty lists, hand-booked entries populate 'documents' while pipeline-created entries carry their document via source_ref_* instead, and the access level is 'Member read'. It omits not-found/error behavior and pagination, but the return-semantics disclosure is substantive.

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 dense, jargon-laden paragraph riddled with internal references ('Gap B', 'R2-13b') and backtick-quoted field names, with no front-loaded purpose statement. Much of it reads as implementation notes about return payload structure rather than guidance an agent needs to select and invoke the tool.

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

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

Because there is no output schema, the description legitimately needs to explain the return payload, and it does so thoroughly (VAT postings, zero-posting declarations, open items, documents). However, it is incomplete on the invocation side: no parameter guidance, no usage routing, and no error behavior for a two-required-param tool.

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

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

Schema description coverage is 0% and the description never mentions entry_id or company_id, so it adds no meaning to either required parameter. It references 'lines[].vat_code' and 'source_ref_*' fields of the payload but not the inputs, leaving the caller to infer how to identify the entry being fetched.

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 'One entry + lines' which implies a single-entry detail read, but frames the tool almost entirely around return payload content rather than stating a clear verb+resource purpose (e.g. 'Retrieve a single GL journal entry by ID'). It never explicitly distinguishes itself from the sibling list_gl_journal_entries beyond the implied singularity of 'one entry'.

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

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

The only usage-relevant statement is 'Member read, like the rest of the detail,' which implies read-only access but gives no when-to-use context. It does not say when to prefer this over list_gl_journal_entries, get_gl_account_ledger, or entry_candidates, and offers no exclusions or prerequisites.

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 must carry behavioral disclosure. It usefully adds company scoping and a 404/403 error split, which implies tenant isolation and access control, but omits whether it is read-only, what auth is required, and what the return shape looks like.

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 wasted words. It delivers the core operation, scope, and error behavior efficiently.

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 get-by-id tool with no output schema, the description covers purpose, company scope, and error semantics. However, it remains silent on ID format, authorization requirements, and what an intake row contains, leaving some gaps for an agent to infer.

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

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

Schema description coverage is 0% and the single parameter (intake_id) has no format details in the schema. The description only says 'by id,' which is essentially a restatement of the parameter name and does not compensate for the missing format or constraints.

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 ('Get') and resource ('intake row') with an ID-based scope, so the operation is clear. It does not explicitly differentiate itself from sibling tools such as upload_intake, but the retrieval-by-id framing is distinct 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?

There is no guidance on when to use this tool versus alternatives, nor any prerequisites for use. The 404/403 note is behavioral detail rather than usage guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and provides none: no permission requirements, no statement of what is returned, no error behavior for unknown IDs. An agent learns nothing beyond the bare existence of the operation.

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 fragment with no waste, but it is under-specified rather than concise. Brevity here reflects missing information, not efficient communication.

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 lookup with no output schema and no annotations, the description should at minimum explain what metadata is returned and how item_id is formed. Neither is present, and '(any source)' leaves the resolution rules opaque.

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% for the single required item_id, and the description adds no format, type, or example for it. '(any source)' very slightly implies the ID is source-agnostic, but that is not enough 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?

The description is a noun phrase with no verb, essentially restating the tool name 'get_item' as 'Item metadata'. The parenthetical '(any source)' hints at scope but does not clarify whether this returns a single item, its type, or which fields.

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 guidance, no prerequisite, and no named alternative such as list_items or a source-specific getter. '(any source)' only weakly implies this spans sources where other tools might not, leaving routing to 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?

With no annotations, the description carries the full burden and does well: it declares 'Read-only', specifies that a non-member company_id yields 403, and explains default resolution for fiscal_year (latest FY with journal data; FY figures frozen at that year's end once past; aging/forecast anchored to today). Only rate-limit/performance behavior is absent, which is minor for a read-only report.

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-loads the headline purpose, then layers data sources, permissions, and the parameter default in dense but non-redundant sentences. Every clause carries information; slightly telegraphic phrasing but 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?

With no output schema and no annotations, the description is the sole carrier of context and covers what is returned, where it comes from, who may call it, and how the fiscal_year default resolves. It stops short of listing the individual KPIs, but is otherwise sufficient for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It gives rich semantics for fiscal_year (optionality, default resolution, as-of-year-end behavior) but explains company_id only indirectly via the 403 membership note, leaving its format/identity unclear. Partial compensation only.

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 (KPI report / snapshot) and enumerates exactly what it contains: snapshot KPIs plus a 13-week liquidity forecast drawn from the GL. It also names the underlying data sources (posted/reversed journal lines, gl_open_item, salary batches, VAT periods), which cleanly separates it from siblings like gl_balance_sheet or gl_profit_and_loss.

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 by the content scope (a KPI/liquidity snapshot), but the description never says when to pick this over the many sibling reporting tools (get_financial_statements, gl_trial_balance, reconciliation_summary) or any exclusion conditions. An agent gets the gist but no explicit routing.

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 discloses scope and severity ordering, but not auth/company requirements, pagination, read-only safety, or response shape. This is minimal transparency for a list-retrieval 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?

A single sentence, front-loaded and free of filler. It is concise, though it omits necessary specifics rather than being verbose.

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 list tool with no annotations or output schema, the description is too thin. It does not cover parameter semantics, usage context, or return behavior beyond the general 'everything waiting' phrase.

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 only parameter company_id is undocumented in both schema and description. 'In this company' hints at the parameter's domain but adds no format, ID type, or requiredness details beyond the schema property name.

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?

Conveys scope ('everything waiting for this user in this company') and ordering ('most severe first'), but does not explicitly name the resource as work items/tasks or distinguish from many sibling list/get tools. An agent can infer a prioritized work queue but cannot confidently tell it apart from other pending-item endpoints without schema inspection.

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?

No when-to-use guidance, prerequisites, or alternatives are provided. The description gives no indication of when this tool should be selected over siblings such as entry_candidates or list_autopost_decisions.

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 so well: it discloses the accounting quirk that assets == liabilities_and_equity, that net_result folds into liabilities_and_equity, and that equity is empty unless the opening batch is present. It also notes the fiscal_year_cut behavior (stamped fiscal_year_id, not posting date). Missing only permissions/cost/volume behavior, which is minor for a read report.

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 purpose is front-loaded and each subsequent sentence adds a distinct caveat rather than restating. It is dense and slightly cluttered by ticket references (ZET-155, ZET-166) and parentheticals, but the length is justified by the accounting subtleties being disclosed.

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 report tool with no annotations and no output schema, the description supplies the semantic frame an agent needs (position vs movements, equity/net_result folding, year cut basis). It stops short of naming the returned fields or shape, which is the one gap given the absence of an 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 0%, so the description must compensate, and it does for the two non-obvious parameters: fiscal_year defaults to the latest posted year with no all-years mode, and period_id turns the result into a movements aggregate. company_id is left undocumented, but its meaning is self-evident from the context.

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 opening sentence states a concrete output (assets vs liabilities + equity) for a specific scope (one fiscal year) with a stated convention (signed by natural side). It does not explicitly distinguish itself from close siblings like gl_profit_and_loss or gl_trial_balance, only borrowing trial-balance window rules, so it stops short of a 5.

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

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

It gives meaningful context - default fiscal_year is the latest posted year, there is no all-years mode, and passing period_id switches to a movements aggregate rather than a position. However it never states when to choose this tool over gl_profit_and_loss or get_financial_statements, so guidance is implied rather than explicit.

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 behavioral burden. It usefully discloses that results are ranked by ts_rank_cd and that archive_status constrains item results only, but says nothing about read-only nature, auth requirements, or pagination semantics despite having limit/offset parameters.

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 short and front-loads the core capability, but the '(A1)' and 'scoped' fragments are opaque internal references that consume space without helping an agent decide or invoke correctly.

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 8-parameter tool with 0% schema coverage, no annotations, and no output schema, the description covers only one parameter's semantics and omits pagination and result-shape context. It is materially incomplete for correct invocation.

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

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

Schema description coverage is 0% across 8 parameters, so the description must compensate. It only explains archive_status (which filters only items), leaving q, type, limit, offset, source, direction, and company_id entirely undocumented.

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: full-text search across emails and items, with a disclosed ranking function (ts_rank_cd). This distinguishes it from sibling listers like list_items, though the cryptic 'scoped (A1)' fragment adds no specificity.

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

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

There is no when-to-use guidance against alternatives such as list_items or get_item. The only partial hint is that the Archive page passes 'archived', which explains one caller's behavior rather than when an agent should choose global_search.

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 so richly: it documents default fiscal-year behavior, period narrowing, 404/422 error semantics, flow-statement reasoning, opening-batch exclusion, and the fiscal_year_id FK cut. This is unusually thorough behavioral context beyond what any structured field provides.

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

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

The description is front-loaded with purpose and uses bold section headers for the window and cut semantics, making it navigable despite its length. Some parenthetical internal ticket references (ZET-155, ZET-166) are noise for an agent, but the information density remains high.

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 no output schema, no annotations, and a complex cut/window model, the description is complete enough: it implies the three return totals from the opening formula, notes the fiscal_year_cut output field, and covers routing, errors, and edge cases. An agent has what it needs to call this correctly.

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

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

Schema coverage is 0%, so the description must compensate. It explains fiscal_year defaults and period_id narrowing plus their error interactions, but leaves company_id implicit and does not elaborate on type/format details already visible in 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 opening formula 'Revenue − expense → net result, for one fiscal year' states exactly what the tool computes and its scope. It explicitly distinguishes itself from the trial balance and the full financial-statements route, so an agent can identify the tool without inspecting siblings.

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 directly names the alternative: 'For the full statement ... use GET /companies/{id}/financial-statements' and explains that this route is for the three totals. It also states the window rules and the absence of an all-years mode, giving clear conditions for selection.

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 delivers: default resolution, 404 vs 422 error semantics, the double-counting hazard, and the fiscal_year_id vs posting-date cut distinction. It stops short of auth/permission needs or rate 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?

The core scoping statement is front-loaded and dense with useful facts, but the final paragraph about cut semantics is convoluted, and internal ticket references (ZET-155, ZET-166) are noise that consume space without helping an agent invoke the tool.

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

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

With no output schema and no annotations, the description supplies the return shape at a high level (columns plus totals), error behavior, and cut semantics. It is nearly sufficient, missing only detail on the exact column set and whether totals are included per account or only overall.

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 and largely does: fiscal_year is a year label defaulting to the latest posted year, period_id narrows within that year, and account identity is the (company, fiscal year, code) tuple. It never states the accepted type/format for company_id or period_id, leaving some gaps for a 0%-coverage 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 opening clause names a specific verb/resource pair: per-account debit/credit columns for one fiscal year with totals. It differentiates itself from the financial-statements path by cut semantics, but does not address how it differs from gl_balance_sheet or get_gl_account_ledger, which an agent could plausibly confuse with a trial balance.

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 explains that fiscal_year defaults to the latest posted year, that period_id narrows to one period, and explicitly warns there is no all-years mode because aggregation double-counts. It also names a contrasting path (…/financial-statements) and when the two diverge. No explicit 'use this instead of X' routing to the other GL tools.

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 so richly: it describes the transaction (number assignment, journal entry debits/credits, open item creation), the state transition to issued, the 409 on re-issue, the renderer-outage tolerance, and that there is no un-issue (reverse the journal entry instead). This is the kind of behavioral context annotations could never supply.

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 essential purpose in bold, then structured by transaction behavior, preconditions, returns, and undo path. It is dense and markdown-heavy, but every sentence carries distinct information, so little is wasted for a tool with this much behavior to convey.

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 no output schema, the description still documents the return value (issued invoice with document_no and commercial_document_id), the failure modes, the readiness check, the renderer-outage edge case, and the reversal path. Nothing an agent needs in order to invoke and interpret this 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 0%, so the description should compensate, but it only indirectly references invoice_id ('the draft') and never explains company_id or the identifier formats. The two parameters are self-evident strings, so this is adequate rather than deficient, but it adds little 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?

States a specific verb+resource (issue a draft AR invoice) and frames it as 'the booking step (accountant role)', which immediately separates it from create_ar_invoice and get_ar_invoice. An agent can tell what this does without opening any schema.

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

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

Explicitly states the precondition (only a draft can be issued) and enumerates refusal conditions: not ready (no customer/lines/revenue account), issue_date outside an open period, no AR control account. It even points to the readiness endpoint whose 'blocking' list maps to the refusals. It does not name sibling tools to use instead (e.g. create_ar_invoice), so 5 is not warranted.

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 provided, so description carries full burden. It discloses ordering (newest first), documented error behavior with 422 and exact message for malformed period, and explains status semantics (paid/overdue derived, not stored). Missing pagination default/max info that schema provides.

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; primary action and ordering front-loaded, then filters, then error behavior. Zero 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?

Covers purpose, filters, ordering, error handling, and key semantics. For a read-only list tool with no output schema, doesn't describe return format or pagination beyond defaults, but annotations absence is mitigated by detailed filter semantics.

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 description must compensate. It adds meaning for status (editorial lifecycle, paid/overdue derived), doc_type (document kind), period (YYYY-MM format, filters by issue month, error on malformed), going well beyond bare parameter names.

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?

Specific verb+resource (list AR invoices) with scope (authored) and ordering (newest first). This distinguishes it from sibling get_ar_invoice (single) and create_ar_invoice (write).

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

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

Implies usage through describing filters, but does not state when to use this vs list_gl_open_items or other list tools. No explicit when/when-not guidance.

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

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

With no annotations, the description carries the burden and does well: it discloses the default suppression of ai_no_match noise rows, the newest-first ordering key (created_at DESC, id DESC), the 200-row cap, the pagination termination rule, and that the response is a bare list. It omits permission/auth requirements and any cost or rate characteristics, which keeps it out of the top band.

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 and feed semantics are front-loaded, and each subsequent sentence adds operational value (filtering, pagination, hold causes). Some space is spent on internal ticket references (ZET-75, R2-21) and the '(CompanyMember)' parenthetical that mean little to an agent.

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

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

No output schema and no annotations exist, so the description has to define the return shape — it does ('the response is a bare list', plus ordering and the row states). Combined with the pagination and filter guidance, an agent can call this correctly; only auth/permission preconditions and the row field list 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 0%, so the description must compensate, and it largely does: include_no_match, outcome, source_ref_id, cause, limit and offset all get meaning (including the server-side narrowing behavior of outcome/source_ref_id). company_id — the one required parameter — is never explained, and the row-level agent_acceptable flag is mentioned without tying it to a parameter.

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+resource: 'Recent AI-accountant autonomy decisions (CompanyMember) — the activity feed.' It then enumerates the three states the feed surfaces (posted/shadow/held), which cleanly separates it from write-side siblings like accept_autopost_decision and from aggregate siblings like get_work_list or reconciliation_summary.

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 concrete usage rules: set include_no_match=true only for audit, use outcome/source_ref_id to reach held rows beyond the newest-limit window, use cause to isolate one hold cause, and page with offset += limit until a short page returns. It does not name a sibling alternative for the 'what should I review instead' case, so it stops short of full when/when-not routing.

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 behavioral burden and does well: oldest-first ordering, no paging, CompanyMember read permission, the auto_created/ownership_status/needs_ownership_review lifecycle, and the explicit null-vs-zero distinction for statement_count/entry_count. The only gap is that read-only nature is implied by 'list' rather than stated.

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-loads purpose in the first sentence and every subsequent sentence carries operational value (ordering, return fields, null semantics, how to set the ledger code). Slightly dense, 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?

For a list tool with no output schema and no annotations, the description documents return fields, ordering, paging behavior, permission level, and the meaning of special fields — everything an agent needs to call and interpret it correctly.

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

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

Schema description coverage is 0% and the sole parameter company_id is undocumented in the schema. The description implies company scoping ('the company's bank accounts') and the read permission, but never states the expected id format, so it only partially compensates 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 (the company's bank accounts) and pins the exact key it returns (bank_account_id) plus who consumes it (statement import, bank-entry list, reconciliation). An agent can distinguish it from siblings like list_bank_entries or get_bank_status without opening a 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?

Explains the ordering and that there is no filter or paging, and routes to the single-account GET /bank-accounts/{account_id} for counts. It names the workflows that depend on the returned id, giving clear context, but stops short of explicit when-not-to-use exclusions against sibling list tools.

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 supplied, so the description carries the full burden of behavioral disclosure, and it discloses nothing: no mention of read-only nature, pagination behavior, default result window, or the interaction between the many filter dimensions. For a 14-parameter query tool with zero annotation coverage this is a severe 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?

The text is certainly short, but this is under-specification rather than conciseness — the entire body is three words that merely echo the name. There is no front-loaded scope statement or structure to guide a call.

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 14 optional parameters, no required fields, no annotations, and no output schema, the description is completely inadequate. Nothing tells the agent when to combine filters, what the default limit/offset window means, or what a listing looks like, so the definition cannot support correct invocation.

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

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

Schema description coverage is reported at 0% across 14 parameters, and the description adds no parameter meaning whatsoever. Critical filters such as flag, q, reconciliation_status, credit_debit, company_id, and the from/to date range are left for the agent to guess from bare property names, and the mutual relationships between matching/settlement/reconciliation status are unaddressed.

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?

"List Bank Entries" is a tautological restatement of the tool name and adds nothing: no scope, no filtering semantics, no differentiation from siblings like get_bank_entry, list_bank_accounts, or reconciliation_summary. An agent could not tell from this text alone what a "bank entry" is or how this differs from the single-entry getter.

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 provides no when-to-use guidance, no prerequisites, and does not name any alternative. At best, the verb "list" weakly implies a read of many records versus get_bank_entry for one, but that inference is left entirely to the agent.

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 disclose real behavior: it requires a JWT and is scope-filtered so non-admins see only their member companies. However, it omits return format, ordering, and whether the result is paginated, which matters for a list 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?

Two short fragments with the resource and the scoping constraint front-loaded; nothing is wasted. The parenthetical '(jwt, scoped)' is telegraphic but 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 parameterless list tool with no output schema, the description covers what an agent needs to know: the auth requirement and the authorization-scoped visibility. Return shape is unspecified but the operation is simple enough that 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 takes zero parameters, so the baseline is 4; there is nothing for the description to add or clarify. The '(jwt, scoped)' note is context rather than parameter documentation, which is acceptable given an empty schema.

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

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

States a specific verb ('List') and resource ('companies'), which cleanly separates it from the singular sibling get_company. It does not explicitly name or contrast with alternatives, but the verb+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?

Usage is only implied by the name and the scoping note; there is no explicit when-to-use or when-to-prefer-get_company guidance. The 'Non-admins see only their member companies' clause hints at the intended audience without routing the agent between options.

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 the non-obvious repeated-parameter behavior (``?kind=customer&kind=both``) and that results are paginated, which is genuine interface context. However, it omits auth/permission needs, what is actually returned, and pagination defaults, so it only partially covers a read list endpoint.

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

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

Two tight paragraphs with the purpose front-loaded and the `kind` clarification following. The backtick/rst formatting is a bit noisy but every sentence adds information, with little waste.

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 list tool with no output schema and no annotations, the description should say more about the return shape and the remaining filter/paging parameters. It covers the trickiest parameter well but leaves the agent guessing about output and defaults.

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 reported at 0%, so the description must compensate, and it does add real meaning for `kind` — set semantics and query-string repetition — beyond the enum. But it says nothing about `q`, `limit`, `offset`, or the required `company_id`, leaving three of five parameters unelaborated.

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 clear verb+resource ("List a company's counterparties") with scope (filterable, paginated). An agent knows what the tool does, but it never names or distinguishes itself from lookalike siblings such as list_companies or list_payroll_employees, 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?

There is no explicit when-to-use, when-not-to-use, or alternative routing. Usage is only implied by "List a company's counterparties." The kind discussion explains a parameter, not when this tool beats a sibling.

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 behavioral burden. It usefully discloses the non-obvious FY-scoping trait (codes repeat across years), but says nothing about read-only nature, permissions, pagination limits (max 200), or return shape.

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?

Roughly one sentence with the purpose front-loaded, but the double-backtick markup is sloppy and the '(CompanyMember)' parenthetical adds confusion rather than 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 4-parameter list tool with no annotations and no output schema, the description omits pagination behavior, result ordering, and any indication of what a chart entry looks like. The FY-scope note is the only substantive addition.

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% across 4 parameters. The description explains fiscal_year's semantics well, but limit, offset, and company_id are entirely undocumented anywhere, so the description fails 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?

The description names the resource (chart of accounts) and the verb (list), but the parenthetical '(CompanyMember)' is opaque internal jargon and the phrase 'postable chart' is ambiguous. It does not distinguish this list tool from siblings like get_gl_account_ledger or list_gl_open_items.

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 a concrete condition for using the fiscal_year parameter ('filters to one year's chart'), which implies when the filter matters, but offers no guidance on when to prefer this tool over allied tools such as get_gl_account_ledger or gl_trial_balance.

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

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

With no annotations, the description carries the full burden and does disclose non-obvious behavior: the filter is applied before the count, so 'total' is the filtered total and the pager reflects the narrowed set — a real semantic fact an agent could not infer from the schema. It omits read-only confirmation, pagination defaults, and auth requirements, so it is not complete.

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 large share of the text is a historical bug narrative with internal ticket references (ZET-285, ZET-150, ZEN-42) that do not help an agent invoke the tool. Meanwhile, genuinely needed content (what 'q' and 'status' filter on) is absent, so the space is allocated poorly rather than efficiently.

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 10-parameter, no-annotation, no-output-schema tool, the description leaves seven parameters undefined and says nothing about the shape of a returned journal entry or pagination behavior. What it does cover is deep but too narrow to make the definition callable with confidence.

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 only documents 3 of 10 parameters (period_ids, untagged_subledger_control, origin). The ambiguous ones — 'q', 'status' (untyped string), sort/order/limit/offset — get no explanation at all, leaving most call semantics to guesswork.

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

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

Opens with a specific verb+resource ('List journal entries'), which is enough to separate it from get_gl_journal_entry and the create/post/reverse siblings by name alone. It never explicitly names an alternative, and the bulk of the text is about filters rather than the tool's scope, so it stops short of a 5.

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

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

Gives strong conditional guidance for individual filters ('period_ids narrows to specific fiscal periods, and is how a caller asks for one fiscal year', 'untagged_subledger_control=true narrows to...'), which borders on usage guidance. But it never says when to reach for this tool rather than global_search, list_gl_open_items, or get_gl_journal_entry, and gives no exclusions.

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 largely meets it: it explains that `as_of` reconstructs open amounts from posted journal lines rather than the cached amount, that items are included regardless of current status, that `status` is actively refused rather than silently ignored, and that `original_amount`/`status` on rows remain current facts. It stops short of stating the read-only/no-mutation guarantee explicitly, so not 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?

The purpose is front-loaded, but the body is padded with internal ticket references (ZCT-577 twice), a narrative about how the browser screen used to filter rows, and the throwaway "the screen says so." The core semantics are valuable; the provenance storytelling is not, and it dilutes an otherwise dense definition.

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 6-parameter list tool with no output schema and no annotations, the description covers the tricky filtering semantics and even names two row fields (original_amount, status), which partially compensates for the missing return schema. What remains unstated — pagination behavior and the row shape beyond those two fields — is minor but not fully covered.

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 does so well for the non-obvious parameters: it defines `direction` as a server-side filter, explains exactly what `as_of` computes, and documents the `as_of`+`status` interaction. It says nothing about `limit`, `offset`, or `company_id`, but those are self-evident, leaving only a minor 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?

The opening states the resource precisely (AR/AP subledger open items) and implies the list/pagination verb ("one page"), plus a permission qualifier ("member read"). It is clear what the tool returns, but it never distinguishes itself from siblings such as list_ar_invoices or list_gl_journal_entries, 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?

It gives concrete usage rules for two parameters (omit `direction` for both directions; `status` is refused with `as_of`), which is real when-to-use guidance. However, it offers no routing guidance relative to the many sibling list/ledger tools, so an agent still has to guess whether this or list_ar_invoices is the right 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 full burden and does so: it declares the read scope (CompanyMember read), defines the status lifecycle and which states accept vs refuse postings, states that a posting into a closed period fails, and points to the reopen flow including 'reason required'. This is unusually complete behavioral disclosure for a list 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?

Purpose is front-loaded in the first line, and each subsequent paragraph adds real value (status semantics, filter behavior, sibling exclusion). It is dense and slightly long, with incidental parentheticals (ZET-161), but almost 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?

For a two-parameter list tool with no output schema and no annotations, the description is nearly self-sufficient — it even names the fields each row carries. The remaining gap is the absence of explicit company_id semantics and any note on result size/ordering.

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 fully explains fiscal_year_id ('narrows to one year; omitted, every year's periods come back') but gives no explicit semantics for the required company_id beyond the permission note. One of two parameters is meaningfully covered.

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 ('The company's accounting periods — the months a journal entry may post into') and explicitly distinguishes itself from the sibling list_gl_vat_periods. An agent can tell instantly what it returns and what it does not.

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 when-to-use ('find the period_id a manual journal entry needs, and to check why a posting date was refused') and a concrete when-not/alternative ('This is not the VAT filing calendar — those are the gl_vat_period rows of GET …/gl/vat/periods'). Routing is fully determined.

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, and it discloses nothing — no read-only confirmation, no scoping, no pagination or auth notes.

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 text is short, but this is under-specification rather than conciseness — there is no information to be front-loaded or trimmed.

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 parameterized listing tool with no annotations and no output schema, the description is entirely inadequate; an agent cannot determine scope, return shape, or how it differs from list_gl_periods.

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 single parameter company_id has 0% schema description coverage, and the description supplies no meaning, format, or source for it. With only one param and no compensating text, this is a clear 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?

The description 'List Gl Vat Periods' merely restates the tool name in title case. There is no elaboration on what a VAT period is, what is returned, or how it differs from the near-identical sibling list_gl_periods.

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?

No when-to-use guidance, prerequisites, or alternatives are given. The presence of a sibling named list_gl_periods makes the distinction especially important, yet nothing in the description helps an agent choose between them.

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 422 error and message for a malformed period, NULL-safe exclusion semantics, that server-side filters keep `total` exact, and the three-valued `posted` logic including the "Already booked" exclusion. Missing only pagination/ordering behavior and what the response body contains.

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 purpose, then organized one filter per paragraph. Dense but nearly every sentence carries semantics; internal ticket references (ZCT-954, ZET-413, ZEN-1) are noise that could be dropped.

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, unannotated, output-schema-less list tool, the description explains the trickiest filters but leaves many parameters and the returned item shape undefined. An agent can call it, but not confidently for the undocumented filters.

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% across 15 parameters, but the description adds real meaning for roughly six of them (`period`, `exclude_triage_status`, `q`, `duplicate`, `credit_note`, `posted`), including substring/wildcard handling. `paid`, `source`, `direction`, `archive_status`, `company_id`, `counterparty_id`, `triage_status`, `limit` and `offset` remain undocumented in both places, which is a large uncompensated 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?

Opens with a specific verb+resource ("List/filter items") and states the access scope (caller's member companies). It never distinguishes itself from nearby siblings such as get_item, list_ar_invoices or global_search, so an agent must infer which listing tool applies.

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 through filter narratives ("Payables/Receivables pass unrelated, so parked items show only in the Inbox"), which hints at how the tool is used in practice. There is no explicit when-to-use / when-not-to-use statement or named alternative for retrieving a single item vs a filtered list.

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 discharges it: it declares the accountant role and that the payload is personal data (auth implication), states there is no server-side filtering and no paging, notes one row per employee including left employees, explains current_contract is null when none is in force, and flags the three-state ahv_pensioner_allowance_waived pitfall that blocks the AHV/FAK declaration.

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 purpose and scope, then return shape, then caveats. Sentences are information-dense and each earns its place, though the multi-paragraph layout is longer than strictly necessary and the field enumeration could be tightened.

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

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

With no output schema and no annotations, the description does the work by enumerating the returned fields (employee_no, display_name, address, ahv_number, birthdate, qst_liable, iban, current_contract, readiness) and their null semantics. Only the missing parameter explanation keeps it from being fully 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?

The schema has 0% description coverage on the single required company_id, and the description never mentions or explains that parameter — it only implies company scoping via 'the payroll master data'. With low coverage the description is expected to compensate, and it provides no added meaning for the parameter.

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 ('every employee on the payroll master data, with today's contract') and immediately distinguishes scope (accountant role, personal data, not a plain member read). It also names a differentiating sibling, the single-employee GET for children/contract history, so an agent can route without opening a 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?

Gives clear context and prerequisites: 'filter on status/employment_end yourself — no server-side filter, no paging' and 'read readiness before creating a payroll run', plus a pointer to GET …/employees/{employee_id} for children and contract history. It stops short of naming sibling list tools to use instead, but the when-to-use conditions are explicit.

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 so: read-only ('CompanyMember read'), no per-employee PII, no paging, lifecycle semantics (draft→...→locked, plus reversed), corrections/reversals as separate runs linked by original_run_id/reversed_by_run_id, journal_entry_id null before posted, per-row metrics, error_count blocking approval, and staleness computed at read time. This is rich, accurate behavioral context.

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

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

Long but tightly structured, front-loading the resource and scope before lifecycle and field detail. Every sentence contributes domain information, though the density is higher than strictly necessary for a list 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?

No output schema or annotations exist, so the description must supply return semantics and behavioral traits — and it does, covering row contents, lifecycle stamps, metrics, staleness, filters, and lack of paging. An agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate; it explains year (runs whose period starts that calendar year) and status_filter (narrows to one lifecycle state, with states enumerated in the prose) while company_id is self-evident. It adds real meaning beyond the bare schema types, though it doesn't document allowed value formatting exhaustively.

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 scope clearly: 'The company's payroll runs — one per wage period — newest period first', including the read-only nature and that amounts are aggregate. Distinguishes itself from the due-endpoint variant, but does not explicitly differentiate from sibling tools such as list_payroll_employees.

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?

Explains filter usage (status_filter narrows to one lifecycle state, year to period-start year) and names an alternative endpoint for wage months that have no run yet. However, it gives no explicit when-not-to-use guidance or direct comparison to the other payroll/list tools.

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 disclose real behavior: it sits in the tier listed for every caller, find_operations reaches it but ranking is unreliable, and an onboarding-scoped API key exists solely for this job. It never explicitly states the tool is side-effect-free (implied by 'guide'), but the auth/discovery context is unusually rich.

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 purpose is front-loaded in the first sentence, but two of the four paragraphs are meta-commentary about discovery mechanics and tier listing that, while marginally useful in discouraging redundant search calls, is verbose for a zero-parameter guide. It could be tightened without losing the routing signal.

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 parameterless informational tool with no annotations and no output schema, the description covers what it is, when to read it, what it contains, and its discovery/auth context. It stops short of sketching the return shape, though the 'fifteen sections' framing implies it.

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. The description's detail about 'fifteen sections' and which documents produce them describes the tool's content rather than adding parameter meaning, but there are no parameters whose semantics are left unexplained.

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

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

States a specific verb and resource: 'How to onboard and create a NEW company,' and enumerates the scope ('what to ask the user for, which documents to request, and the order to run the setup in'). It partially differentiates from siblings by contrasting with find_operations and the create tool's schema, but never clarifies its relationship to plausible near-siblings like start_signup or collect_api_key.

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 when-to-use guidance: 'Read this before you start a company setup, and before you tell a user that something cannot be done here.' It also explains the discovery condition that selects it over search. However, it offers no exclusion rules against the other onboarding-flavored siblings.

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 so well: it discloses irreversibility, the 409 refusal on replace/discard, the reverse-and-leave-both-visible recovery path, and the single in-place exception (guessed-account on a coding_guessed entry). This is exactly the failure mode an agent would otherwise trigger.

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 its 'One-way' warning, then three tight sentences on consequences. Slightly heavy use of code-path fragments ('…/reverse', 'PUT …/guessed-account') and 'ZET-159'-style references outside the description, but no wasted prose.

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 description covers the important danger zone (irreversibility, error codes, recovery). It stops short of stating auth/role requirements beyond the word 'accountant' and never describes what posting returns.

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?

Top-level schema description coverage is 0% and the description mentions none of entry_id, company_id, or the body flags. The nested body properties (not_vat, allow_untagged_control, confirm_bank_duplicate) are documented in the schema only, and the description never connects them to the error paths it warns about — so it fails 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+resource ('Post a draft entry into the books') and immediately pins it to a role ('accountant') and a one-way nature. That plus the reference to '…/reverse' cleanly separates it from create_gl_journal_entry (draft creation), get_gl_journal_entry (read) and reverse_gl_journal_entry (correction).

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 clear operational context: verify the draft first because posting is irreversible, and reserve the guessed-account PUT for one specific case. It does not explicitly name create_gl_journal_entry as the precondition tool, so the routing to the correct sibling for drafting is left to 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?

With no annotations, the description carries the full behavioral burden, and it discloses a genuinely non-obvious trait: the from/to window scopes only the per-entry counts, while cross-month gap detection remains global. That asymmetry is the kind of thing an agent could not guess. It still omits auth/permission requirements and the return shape.

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 purpose, then the scoping rule and its limit in two tight sentences. The stray 'Reconciliation summary banner.' lead is close to redundant with the title-like name, but the rest earns its place with no 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?

There is no output schema, so the description must convey return content; it does name the key fields (counts, gaps, missing_periods) but does not enumerate the fields fully or explain company_id. Adequate but with clear gaps for a 3-parameter report tool.

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

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

Schema description coverage is 0%, so the description must compensate. It explains from/to semantics well (booking_date window, mirroring the grid filter) and reveals their partial effect on the result, but says nothing about the required company_id parameter or the expected date format.

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

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

The body states a concrete verb+resource: it returns a reconciliation summary containing per-entry bank-entry counts (total/matched/missing-invoice) plus cross-month coverage (bank_accounts gaps, missing_periods). The opening line 'Reconciliation summary banner' is thin on its own, but the following sentences make the output content unambiguous. It does not, however, distinguish itself from near-neighbours like get_bank_status or list_bank_entries.

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 explains what the optional from/to do and that they mirror the /bank-entries grid filter, which implies usage for month-filtered views. But it never states when to call this rather than list_bank_entries, get_bank_status, or list_bank_accounts, nor any prerequisites beyond the required company_id.

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 so richly: returns a plain `verification_uri`, an email notice is also sent, no code exists in either direction, the user chooses the key's scope on the page, and a 403 outside that scope should be read as scope, not failure. It also discloses the enumeration-resistant behavior (same answer whether or not the address has an account), which an agent could not infer from the 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?

Front-loaded with the imperative 'Use this first' and organized in short paragraphs that each carry a distinct instruction. Some emphasis is repeated for effect ('There is no code... nothing to read out, nothing to type, nothing for you to put in a link'), which is defensible anti-error reinforcement but slightly verbose.

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 or annotations exist, so the description must cover returns and lifecycle, and it does: the return value, the asynchronous polling contract with the sibling tool, the status field to watch, and the scoping/403 edge case. Nothing an agent needs to initiate and complete this flow 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 0%, so the description must compensate, and it does for both parameters: `email` is the address on the user's Zeno account, must be asked for rather than guessed, and 'aims' the request so only that owner sees it; `client_name` is the only identifier shown on the approval page and its absence makes the client look unnamed. This is meaning well beyond the untyped string properties.

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: obtain a Zeno API key for the current session via a user-approved flow. It immediately distinguishes itself from siblings by naming `collect_api_key` as the follow-up and `email`/`client_name` as its inputs, so an agent can tell it apart from the many read/write Zeno tools 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?

Explicit sequencing: 'Use this first', then call `collect_api_key` with the returned `claim_token`, waiting `poll_interval_seconds` until status stops being `pending`. It also names the non-obvious alternative context (every current Zeno user already has an account) and warns not to assume a mistyped address is a missing account.

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: it discloses that nothing is deleted, the original is retained and linked, the reversal entry is returned, and VAT postings/open items/document side effects are unwound. It also lists the specific 409 triggers and the closed-period correction procedure, which is exactly the behavioral context an agent needs before invoking a mutation.

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 in the first line, then parameter behavior, then failure modes — a logical progression. Markdown bolding and backticks add slight visual noise, but every sentence carries information.

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

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

No output schema exists, yet the description states the reversal entry is returned; it covers side effects, defaulting behavior, closed-period handling, and the full set of 409 reasons. Nothing an agent needs to call this mutation safely 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 0%, so the description must compensate. It does for the one non-obvious parameter: body.posting_date determines the reversal's date and period, and defaults to the original's date when omitted. entry_id and company_id are left implicit, which is reasonable since their meaning is self-evident, but it keeps this from a 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 ('Storno a posted journal entry: post its mirror image') and scopes it to an accountant role. The word 'Storno' plus 'mirror image' makes clear it is not the same as create_gl_journal_entry or post_gl_journal_entry, even without reading their schemas.

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

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

'The only VAT-correct storno door' explicitly routes the agent here rather than to a manual reversal, and the 409 paragraph enumerates concrete conditions where the call will fail. It stops short of naming alternative siblings or a fallback path when a 409 occurs, so not quite 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?

No annotations, so the description carries the full burden and does well: it discloses idempotency, the no-op/skipped behavior when the GL chart isn't configured for native settlement, the exact double-entry posting rules per match state, and that the matcher still owns reconciliation_status. The only gap is it doesn't state auth/permission requirements or what the response payload looks like.

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-loads the core action, then enumerates the branch-specific postings compactly. The doc reference is a useful pointer but slightly lengthens it; overall still tight.

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-param mutation tool with no annotations and no output schema, the description covers behavior, side effects, and idempotency well. It leaves parameter identity underspecified and doesn't mention permissions, but the core semantics are 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 description coverage is 0% and parameter count is 1, but the description says nothing about what entry_id refers to (a bank entry ID from which system) or its format. Baseline for 1 param with no description is weak; the description does not compensate.

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

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

States a specific verb+resource (Post ... bank entry into the GL) plus a parenthetical scope qualifier (clean-bank settlement). This clearly distinguishes it from siblings like post_gl_journal_entry or reverse_gl_journal_entry.

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 explains the conditions that select each posting variant (matched vs unmatched vs previously-suspensed) and notes the no-op case, which effectively tells the agent when the tool will vs won't do anything. It doesn't name an alternative tool explicitly, but the conditions are clear.

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 delivers: it explains the email-verification handshake, that the agent never sees the link and must not ask for it, that client_name appears as an unverified claim, and the terminal 'denied' outcome. This is unusually rich behavioral disclosure for a write/identity 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?

Front-loaded with the core action, then sequencing, then guardrails, with no filler sentences. It runs longer than most definitions, but each paragraph carries distinct operational content rather than restating the name.

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

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

No annotations and no output schema, yet the description covers actor, side effects, the returned claim_token, the follow-up tool, and terminal states. Nothing an agent needs to invoke start_signup 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 0%, so the description must compensate, and it largely does: email is explained as the mailbox that receives the verification link, and client_name as the name shown to the user as an unverified claim. It never states that email is required or gives formatting constraints, leaving a small 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: 'Create a Zeno account for somebody who does not have one yet.' It immediately distinguishes itself from request_api_key and collect_api_key by name, so an agent can route between the signup-flow siblings without opening schemas.

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 prerequisites and sequencing: use request_api_key first if the person might already have an account, then poll collect_api_key with the returned claim_token. It also states a hard stop condition ('denied is terminal ... do not start another'), which is exactly the when-not guidance an agent needs.

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 disclose key side effects: it 'Creates Item(s) and queues extraction', and it explains the misrouting behavior. It stops short of stating permission requirements, whether uploads are idempotent, or limits on file size/count.

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-loads the purpose and accepted types, then the routing warning in a clearly marked final paragraph. Slightly verbose around the backtick-quoted parameter names, but no sentence is wasted.

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

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

For a 0%-coverage, no-annotation, no-output-schema mutation tool, the purpose and routing story are complete, but gaps remain: two parameters are undefined and no auth/idempotency behavior is given. Adequate but not fully self-contained.

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 usefully defines file_base64 (raw bytes, base64-encoded) and direction (payable vs receivable), covering two of four parameters, but leaves filename and company_id undocumented in both the schema and the description.

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 ('Upload an INVOICE or RECEIPT ... for analysis') and immediately scopes the file types accepted (PDF, image, .zip). It also explicitly distinguishes itself from the sibling upload_intake, so an agent can route without inspecting either schema.

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

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

Gives an explicit when-not: 'For anything that is not an invoice — or when you are not sure what the file is — use upload_intake.' It also describes the consequence of misrouting (file is analysed and sits as a document), which is exactly the decision support an agent needs.

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 so: it discloses the 202 async response, that routing happens asynchronously, that the agent must poll get_intake, that unroutable files become failed queue rows with a reason rather than being dropped, and the downstream effects (BankStatement + BankEntry rows matched by IBAN, zip expansion).

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 purpose, then the routing list, then return/poll behavior. Dense and largely free of filler, though the long enumerated file-type list plus zip note is slightly heavy for a single sentence run-on.

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 and no annotations, yet the description covers the response (202 + queue row id), the follow-up call (get_intake), failure semantics, and per-file-type routing outcomes — everything an agent needs to invoke and complete the flow.

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 description must compensate. It clarifies file_base64 as raw bytes base64-encoded, but filename and company_id are left undescribed — company_id in particular is non-obvious in a multi-company context and could need scoping rules. Partial compensation warrants 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 concrete verb+resource ('Upload ANY file') and immediately pins the scope to the unified intake queue, equating it with the 'Documents → Upload' web-app door. This clearly separates it from the sibling 'upload_document' and from invoice-specific creation tools.

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 routing rule: prefer this 'whenever the file is not plainly an invoice', with an enumerated must-use list (bank statements in CAMT.053/CSV/PDF/Excel, journal exports, balance sheets, P&L, VAT filings, mixed zips). It tells the agent both when to use it and, by saying 'not plainly an invoice', when to prefer the invoice path.

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 delivers: it discloses read-only/cheap behavior ("at most one lookup"), auth semantics (jwt or API key), the company-scoping enforcement including that admin endpoints are refused, the memberships withholding rule, and that MCP-recorded actions display as MCP. This is unusually rich behavioral disclosure.

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 first sentence is well front-loaded, but the body is a dense wall of text with internal ticket references (ZET-171, ZET-176, SP-08, SP-12, PRE-03/PRE-04) that mean nothing to an agent, plus convoluted phrasing like "worth nothing outside this company, still full authority inside it." Much of the content earns its place given no output schema, but the noise and length cost it.

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, so the description must explain the return shape — and it does, defining every field's meaning and the null-vs-empty distinction for memberships. For a zero-parameter identity/scope probe, nothing an agent needs to interpret the result 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?

The tool takes zero parameters, so the baseline is 4. The description instead invests heavily in output-field semantics (company_scoped, company_id, company_name, is_admin, memberships, credential_purpose, capabilities), which is valuable but belongs to return-value interpretation rather than parameter meaning.

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 opening sentence states a specific verb and resource: which user the request acts as and which company's books it is bound to. It is clearly distinguished from siblings like get_company or list_companies, which fetch company data rather than resolving the caller's own identity/scope.

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?

"Call this FIRST when working over MCP" is explicit, actionable timing guidance. It lacks an explicit when-not or named alternative, but the tool is effectively a singleton prerequisite so the missing exclusion is minor.

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 so reasonably: it declares that no credential is needed (an auth requirement) and describes what the response contains (an authentication block naming credential tools). It stops short of describing cost or side effects, though for a zero-param info tool there is little else to disclose.

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, the key fact (no credential) bolded and front-loaded before the diagnostic use case. Minor awkwardness in the fragment-style first sentence, but no waste.

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 parameterless read-only info tool with no output schema, the description is nearly complete: it covers auth needs and the shape of the useful return. Only the sibling disambiguation 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; the description correctly implies a no-argument call and adds nothing misleading about inputs.

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 content set: server identity, MCP revision, and credential acquisition, so the agent knows what it returns. It does not differentiate itself from close siblings like zeno_overview, onboarding_guide, or whoami, which is the main gap.

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 trigger: call it first after a tool has refused you, and it will name the tools that can establish a connection. Clear context, but no explicit when-not or comparison against the overview/onboarding siblings.

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 and no output schema, the description carries the full burden. It usefully discloses the auth profile ('Needs no credential') and scope ('one page'), which an agent cannot get from the empty schema. Beyond that it says nothing about the return format or structure, so it is only partially transparent.

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 statement, then two tight sentences covering auth requirements and the trigger for reading it. The bolded credential note is well placed and every sentence earns its place.

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 informational tool with no output schema, the description covers purpose, auth profile, and usage trigger adequately. It could say a bit more about what the page actually returns, but nothing critical for invoking the tool 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?

The tool takes zero parameters, so there is no parameter semantics to add and the baseline of 4 applies. Schema coverage is nominally 100% (vacuous), and no meaningful param detail could be provided.

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 scope: an overview of the platform's capabilities and limits, plus the topic areas it covers (VAT, payroll, reconciliation, AI accountant). The purpose is clear, but it does not distinguish itself from closely related meta-siblings such as zeno_info, describe_operations, or onboarding_guide, leaving the agent to guess which overview-named tool to pick.

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 trigger condition — 'Read this before telling a user that Zeno cannot do something' — which is a genuinely useful when-to-use cue. It offers no exclusions or explicit comparison to the other informational siblings (zeno_info, describe_operations), so it stops short of full alternative routing.

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