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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds that it scopes to the active company and lists the returned settings categories, but says nothing about permissions, error behavior, or what happens if no config exists.

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 sentences with zero filler; the core action and scope come first, followed by a compact enumeration of the return payload. 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 a parameterless read-only getter with full schema coverage and no output schema, the description supplies the one thing that would otherwise be missing: what the response actually contains (account codes, journal mappings, export preferences per integration). Minor residual gap is the absence of any note about unconfigured companies.

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

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

Schema description coverage is 100% with the single optional companyId already documented as a UUID override that defaults to the active company. The description's mention of 'active company' is consistent with, but not additive to, the schema, so the baseline 3 applies.

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

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

States a specific verb ('Get') and precise resource ('accounting export configuration for the active company'), and enumerates the target integrations (Saga, Winmentor, Ciel). It is clearly distinguishable from accounting_export_settings_update by its read semantics, though it never names the sibling tools explicitly.

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

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

Usage is implied by the read-only 'get configuration' framing and the mention of account codes/journal mappings, but there is no explicit when-to-use guidance, no statement of prerequisites, and no pointer to accounting_export_settings_update or accounting_export_zip as alternatives.

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

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

Annotations already declare idempotent=true, destructive=false, and closed-world, so the safety profile is covered. The description adds genuinely valuable context beyond that: settings are MERGED with existing config (partial update semantics) rather than replaced, and it names which export targets are configurable. It stops short of describing error behavior or permission requirements.

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

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

Three short sentences, front-loaded with the action and scope, followed by the merge semantics and then the content categories. No filler; only minor cost is that the provider list trails rather than being integrated with the settings sentence.

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

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

Given a nested, opaque settings object and no output schema, the description does a reasonable job but does not state what a successful response contains or what happens on conflicting keys during merge. For a mutation with a free-form payload, an agent would still benefit from knowing whether unknown keys are rejected or ignored.

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

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

Schema coverage is 100% but the key parameter 'settings' is an untyped free-form object with additionalProperties {}, so the schema itself says almost nothing about valid content. The description compensates by naming the categories of settings (account codes, journal mappings, export preferences) and the provider targets, which meaningfully constrains what the agent should put in that object.

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

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

The description names a specific verb (Update), resource (accounting export configuration), and scope (active company), and identifies the supported providers (Saga, Winmentor, Ciel). An agent can distinguish this from accounting_export_settings_get and accounting_export_zip without reading 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?

Usage is implied by the 'Update' verb and the existence of accounting_export_settings_get, but the description never explicitly says when to use this versus the getter or the zip export tool. No prerequisites or exclusions are stated, 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?

The description adds useful behavioral context by listing the archive contents and explaining SAGA chart-of-accounts overrides with fallback to stored settings. However, it does not disclose important export mechanics such as how the ZIP is returned, whether the operation is asynchronous, or any permission/rate-limit constraints, leaving meaningful gaps beyond the safety annotations.

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 the tool's purpose and then adds archive contents, filtering, and SAGA-specific override behavior. Every sentence contributes useful context without repetition or 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?

Given the 9 parameters, nested account structures, and no output schema, the description gives an adequate high-level picture: what is exported, which formats are targeted, and how SAGA overrides work. It omits some lower-level SAGA flags and delivery details, but the rich schema covers those parameter specifics.

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 already 100%, so the schema documents parameters including target, date filters, accounts, currencyAccounts, and SAGA-only flags. The description adds only limited parameter context: date filtering, the accounts override syntax, and SAGA-only behavior, but does not explain currencyAccounts or the other SAGA-specific flags.

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: export accounting data as a ZIP archive for import into named accounting systems. It also scopes the archive contents, distinguishing it from narrower sibling exports such as invoices_export_zip or clients_export_saga_xml.

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 clearly establishes the intended use case: import into Saga, Winmentor, or Ciel, with optional date filtering. It does not explicitly compare against sibling export tools or state when not to use it, which keeps it below a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real value beyond them: the SUPER_ADMIN authorization requirement, the audit-log data source, the exact metric set, and the full sort ordering (invoices issued, then created, then active days).

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 and scope, then the permission gate, then the use case and sort order. Dense but every clause carries information; the metric enumeration is slightly listy but justified for a report tool with no 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 output schema, the description compensates by naming the returned dimensions (actions, active days, invoices created/issued, last activity, organizations) and the ordering, plus the auth gate and data source. An agent has everything needed to call it and interpret the result set.

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

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

Schema description coverage is 100%, so the schema already documents days (default 30, max 365), limit, and exclude with an example. The description only restates the day-window concept as 'last N days' and adds no syntax or default detail beyond the schema, so baseline 3 applies.

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

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

States a specific resource and scope: per-user activity aggregated from the audit log over a day window, plus the exact metrics returned. An agent can distinguish it from admin_audit_logs (raw log) or admin_stats (platform-wide) by the 'per-user, aggregated' framing, though no sibling is named explicitly.

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

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

'Use to find who uses the platform regularly and who issues invoices continuously' gives a concrete selection context, and 'SUPER_ADMIN only' states the access prerequisite. It stops short of explicitly excluding alternatives (e.g. when to prefer admin_audit_logs or admin_users instead).

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered by structured data. The description adds the privilege requirement (SUPER_ADMIN) and the semantic effect of the exclude filter, which annotations cannot convey; return ordering and pagination behavior are left unstated.

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

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

Three short sentences, front-loaded with purpose, then the access constraint, then the filtering rationale. No filler and nothing repeated.

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

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

For a read-only, fully documented 6-parameter list tool with no output schema, the description covers scope, privilege, and filtering intent. Only the absence of any tie-breaker against sibling admin/admin audit tools leaves a small gap.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema with defaults and an example. The description reinforces the purpose of `exclude` ("so real customer activity stands out") but adds no syntax or constraints beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource ("List platform audit log entries") and enumerates the action and entity scope an agent needs to recognize the data it returns. It does not distinguish itself from the closest sibling, admin_activity, which an agent could plausibly pick instead.

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?

"SUPER_ADMIN only" gives an explicit access precondition, and the note about excluding known users explains the intended investigative use case. It stops short of naming when to prefer admin_activity or admin_users over this tool, so the routing guidance is clear but not exclusionary.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds a genuinely useful behavioral constraint not in annotations — that the tool is SUPER_ADMIN only — plus the paginated nature and the outcome states returned. No rate limits or ordering behavior is mentioned.

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

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

Three sentences, front-loaded with the operation and scope, then the access restriction, then the use cases. No filler and nothing repeated from the annotations.

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 eight-optional-parameter read tool with no output schema, the description covers purpose, auth requirement, returned content and use cases. It omits result ordering and whether a total count is returned, which 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?

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by expanding the category enumeration to all eight lifecycle categories where the schema only lists three examples. It still says nothing about the date-range pair or recipientEmail partial matching, but those are documented 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 description states a specific verb and resource ('List lifecycle email log entries with filtering and pagination') and pins down the exact scope by enumerating the lifecycle categories, which separates it from nearby siblings like admin_audit_logs and invoices_email_history. An agent can identify the resource without opening the schema.

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

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

It gives concrete when-to-use context ('audit delivery, debug suppressions, or check drip cadence') and states the access precondition (SUPER_ADMIN only). It does not name when-not-to-use or point to an alternative log tool, so it stops short of 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?

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description adds genuinely new context: the required SUPER_ADMIN role and the shape of the payload (owner info, plan, member/company/invoice counts, ANAF token status). It omits operational traits such as rate limits or whether pagination metadata includes a total, keeping it short of 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?

Three short sentences, front-loaded with the operation and scope, then the auth gate, then the return payload. No redundancy with the title and nothing 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?

With full schema coverage and read-only annotations, the description covers auth scope and return contents, which is what an agent needs to select and invoke it. The remaining gap is paging behavior (whether a total count or cursor is returned) for an unbounded, filterable list.

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

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

Schema description coverage is 100%, so page, limit, search, plan and status are all documented in the schema itself. The description only gestures at 'pagination and filtering' and hints at the plan field through 'subscription plan', adding no syntax or behavioral detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('List all organizations on the platform') plus the scope (pagination and filtering) and the privilege boundary (SUPER_ADMIN only). An agent can immediately tell this is the platform-wide org listing, distinct from admin_users or admin_stats in the sibling set.

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 'SUPER_ADMIN only' clause gives a hard eligibility gate that tells the agent when this tool is callable and when it must route elsewhere. It doesn't enumerate alternatives, but no sibling overlaps enough to require an explicit exclusion.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered. The description adds two pieces of genuine behavioral context beyond them: the SUPER_ADMIN authorization requirement and the ~5 minute cache staleness window, which matters if the agent is reporting fresh numbers.

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 compact sentences with what-it-returns front-loaded, then the auth gate, then the caching caveat. No filler and no repetition of the annotations.

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-param, no-output-schema tool the description covers the scope of the payload by enumerating the statistic categories, plus the access requirement and freshness caveat. Exact field names and structure remain unspecified, which is the only real 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?

Zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly implies a no-argument, single-shot call.

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 plus resource ('Get platform-wide statistics') with the contents enumerated: user counts, org metrics, company sync status, invoice totals, system info. The 'platform-wide' scope implicitly separates it from dashboard_stats and from narrow siblings like admin_users or admin_organizations, though none are named explicitly.

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

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

The 'SUPER_ADMIN only' line is an eligibility constraint, not a when-to-use rule. It never states when an agent should pick this over dashboard_stats, admin_users, or system_health; the agent must infer that from the 'platform-wide' wording.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-schema information: the SUPER_ADMIN authorization requirement and the shape of what is returned (verification status, role, last login, memberships).

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 compact sentences, front-loading the core action, then the authorization gate, then the payload. Nothing is repeated and nothing is wasted.

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

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

With no output schema, the description's enumeration of returned fields does real work, and the auth constraint plus pagination/filtering note cover the remaining unknowns. An agent has enough to decide and invoke 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 100%, with every parameter documented including the status enum and the limit maximum, so the description only echoes 'pagination and filtering' generically. Baseline 3 is appropriate since the schema carries all 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?

States a specific verb and resource plus platform-wide scope ('List all users on the platform with pagination and filtering'), which implicitly separates it from org-scoped siblings like members_list. It never names a sibling outright, so differentiation is inferential rather than explicit.

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?

'SUPER_ADMIN only' gives a clear precondition for use, which is exactly the kind of context an agent needs before calling an admin endpoint. It stops short of stating when to prefer members_list or admin_organizations instead, so no explicit exclusions are provided.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, but the description adds substantial context beyond them: the SUPER_ADMIN authorization requirement, the return shape (one entry per ios/android/huawei with YAML defaults, live DB override, merged effective values), and the downstream consumer (/api/v1/version). This is exactly the kind of behavioral detail 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?

Three sentences, front-loaded with the action and scope, followed by authorization, return structure, and the sibling alternative. Every sentence earns its place with no repetition of structured fields.

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

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

With no output schema, the description compensates by explaining the return payload in detail. Combined with annotations covering safety and the explicit SUPER_ADMIN gate, an agent has everything needed to call this tool correctly and interpret its output.

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 schema has nothing to document and the baseline is 4. The description correctly does not waste space discussing parameters, though it also does not need to.

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

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

States a specific verb and resource: 'List the per-platform version-gate overrides for the mobile app.' It distinguishes itself from the sibling mutation tool by naming admin_version_override_update and its role (flip the kill switch), so an agent can route correctly 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 a clear precondition ('SUPER_ADMIN only') and explicitly points to admin_version_override_update for the mutation case. It implies this tool is for inspection but does not spell out a 'when not to use' beyond the update alternative, so it falls just short of 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?

Adds substantial context beyond annotations: SUPER_ADMIN auth requirement, audit logging, the independent per-field set/null/omit semantics, and the instant-ratchet effect of raising minOverride. These are real behavioral facts not in the schema or annotations, and are consistent with idempotentHint=true and destructiveHint=false.

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

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

Tight and front-loaded; each sentence adds a distinct operational fact.

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 no-output-schema mutation tool, the description covers who can call it, what each field does, side effects (notification fan-out, blocker ratchet), and audit implications — enough for an agent to invoke 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 100%, so the baseline is 3, but the description reinforces the cross-parameter tri-state contract (string overrides, null clears, omit leaves as-is) and explains notify's ratchet-vs-silent-correction intent, adding genuine value.

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

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

States a specific verb (set/clear), resource (per-field version-gate overrides) and scope (one mobile platform), which cleanly distinguishes it from the sibling admin_version_overrides listter.

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 usage context: SUPER_ADMIN only, and the per-field tri-state semantics. It doesn't explicitly route to a sibling alternative (e.g. admin_version_overrides for reading), but the mutation-vs-read distinction is obvious from the verb.

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

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

Beyond the read-only and idempotent annotations, the description explains that certificates are local to the Storno Agent and distinguishes token certificates requiring a PIN from cloud certificates approved by a vendor app and software certificates requiring no PIN. This adds meaningful operational context, though it does not cover behavior when the local agent is unavailable or how an empty result should be interpreted.

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

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

The description is compact and front-loads the resource and returned fields before explaining certificate-kind semantics and downstream id use. Despite dense parenthetical detail, every clause carries useful information and there is 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 parameters, the description supplies the relevant return fields and their meanings, plus the downstream use of id. It is nearly complete, but it does not state the response container shape or error/empty-state behavior.

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

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

The tool has zero parameters, so there are no parameter semantics to clarify; the baseline for zero-parameter tools applies. The description appropriately does not invent parameter guidance.

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 identifies a specific resource, qualified certificates usable by the local Storno Agent, and enumerates certificate kinds and returned fields. It also distinguishes the tool from signing/submission siblings by pointing to agent_sign_pdf and the submission tools as consumers of the returned id.

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 final sentence clearly establishes when the returned id is needed: before calling agent_sign_pdf or the submission tools. It gives strong context but does not include explicit exclusions or alternatives, so it stops short of a full when/when-not guideline.

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

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

Beyond the annotations, it discloses that the original is untouched and a new <name>.signed.pdf copy is written next to it (or into outDir), that directories are expanded to all *.pdf inside, that PIN resolution follows a fallback chain (pin → STORNO_AGENT_PIN → remembered PIN), and that the batch aborts at the first PIN error to protect the token from lockout. Those are exactly the operational facts an agent cannot infer from the schema or the readOnly/destructive hints.

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

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

Everything is packed into one dense paragraph, but it is front-loaded with the verb and purpose, and each clause carries information (mechanism, examples, input shape, output location, PIN requirements, failure semantics). Slightly long and unsegmented, but no filler sentences.

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 mutation tool with no output schema, the description covers both the effect (a signed copy alongside the original or in outDir) and the failure mode (stop at first PIN error), which substitutes for the missing return documentation. An agent has everything needed to call it correctly and anticipate the results.

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

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

Schema coverage is 100%, so baseline is 3; the description adds real value by stating the output naming convention, that directories are accepted for files, and the PIN precedence order. It still leaves the interaction between visible/signerName and the default (certificate subject) largely to the schema, so it is good rather than exceptional.

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

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

The description opens with a specific verb and resource ('Sign one or many PDF files') plus the mechanism (qualified certificate via the local Storno Agent, PAdES/CMS embedded). It is clearly distinguishable from siblings such as agent_submit_declaration_pdf or agent_certificates because it names the input (arbitrary PDF paths/directories) and the output artifact.

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 context ('declarations produced by DUKIntegrator, contracts, any document ANAF or a partner wants signed') and states the certificateId must come from agent_certificates, which is effectively a prerequisite. It does not explicitly say when to prefer the sibling agent_submit_declaration_pdf for declaration flows, so it falls short of a full when/when-not/alternatives answer.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely useful context beyond that: the agent is local to the user's machine and holds the qualified certificate on a USB token, which explains why probing its state matters and implies no server-side side effects. It says nothing about failure modes (what is returned when the agent is offline), which keeps it from a 5.

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

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

Two sentences, front-loaded with the direct question the tool answers, followed by only the context needed to understand what the agent is. No filler, nothing repeated from annotations.

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-param status probe with full annotation coverage and no output schema, the description adequately covers what the call reports and what the agent represents. The remaining gap is the offline case — an agent would benefit from knowing what a negative result looks like or what to do next, but nothing essential 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 nothing to disambiguate and the baseline is 4. The description correctly frames the call as a simple query requiring no 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?

The description states a precise purpose: checking whether the local Storno Agent is running, its version, and update availability — three concrete answers from one call. The second sentence distinguishes the local desktop agent from the cloud backend, which is the key conceptual split against siblings like system_version or agent_certificates, though it never names an alternative explicitly.

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

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

Usage is only implied: an agent would infer this is the pre-flight check before agent-dependent operations (agent_sign_pdf, declarations_file_via_agent), since the description explains the agent holds the signing certificate. There is no explicit when-to-use, when-not-to-use, or pointer to sibling tools such as agent_certificates for certificate details.

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

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

Annotations already cover the safety profile (write, non-idempotent, open-world, non-destructive). The description adds meaningful behavior beyond that: the local agent signs with the certificate, uploads to the portal, returns the ANAF upload index, and the recipisa lands in the SPV inbox and on StareD112. This gives the agent real workflow context that the annotations cannot express.

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 definition is dense but well front-loaded: the action, the artifact, the signing/upload mechanics, the return value, and the prerequisites all appear in order with no filler sentences. It is longer than average but each clause 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?

For a write tool with no output schema, the description explains the lifecycle well: what is returned (upload index), how to track it (anaf_declaration_status with CUI/CNP), and where the recipisa appears. The main omission is that certificateId semantics are never touched, and error/auth failure modes are unmentioned.

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

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

Schema coverage is 50%: file and fileName are documented in the schema, but pin and certificateId are not. The description compensates partially by explaining the three PIN sources (pin argument, STORNO_AGENT_PIN, or the remembered PIN on this machine), which is genuinely useful. It says nothing extra about certificateId, so half the parameters still rely on bare schema.

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

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

The description states a specific verb and resource: it files a DUK-generated declaration PDF at ANAF, signed locally with a certificate and uploaded to WAS6DUS. This clearly distinguishes it from generic siblings like declaration_pdf (a generator) or agent_sign_pdf (signing only). It does not explicitly contrast with declarations_submit or declarations_file_via_agent, 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?

Implicit usage is clear — you need a DUKIntegrator PDF and want it filed. It also names anaf_declaration_status as the follow-up tool for tracking, which is helpful. However, with close siblings such as declarations_submit and declarations_file_via_agent present, it never states when to use this one instead of those, leaving a real routing gap.

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?

Adds real context beyond annotations: max 5 active links per user and short expiry duration, which are operational constraints the agent cannot get from the schema. It does not say what happens when the limit is hit or whether links can be revoked early.

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

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

Four short sentences, front-loaded with purpose then return value then limits. Every sentence carries information an agent needs; 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?

For a zero-param, no-output-schema tool, it covers purpose, return shape (unique URL), quota, and expiry. Only the failure mode at the quota limit and the link's one-time-use semantics are 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 there is nothing to document; the description correctly does not pad with parameter talk. Baseline 4 applies.

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

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

Specific verb+resource: 'Create a device-based authentication token link for completing the ANAF OAuth flow.' This clearly separates it from auth_* siblings (login/register/refresh) and from anaf_tokens/anaf_delete_token, though it does not explicitly name those 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?

It implies usage ('opened in a browser to complete ANAF authentication') but never states prerequisites or when to prefer this over anaf_tokens or the auth_* family. The agent must infer the workflow position.

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

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

Beyond the annotations, it explains the host fallback behavior across three StareD112 hosts, the meaning of each status value, and that it returns the recipisa PDF URL when available. It also clarifies that the service is public and needs no account.

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 the core purpose and then adds only useful operational context: status meanings, host fallback, and the recipisa return. There is no filler, and the single dense sentence remains 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?

With no output schema, the description still explains the possible statuses and the optional recipisa PDF URL. Combined with complete parameter coverage and annotations, it gives the agent enough context to call and interpret 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 coverage is 100%, so the parameter meanings are already documented in the schema. The description reinforces that the index is the upload index and that CUI/CNP identifies the taxpayer, but it does not add materially new parameter semantics, so baseline 3 is appropriate.

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

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

The description names a specific operation and resource: checking ANAF declaration processing status via StareD112 using an upload index and CUI/CNP. It also ties the tool to the preceding upload/submission action, making it easy to distinguish from general declaration 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?

It clearly states when to use the tool: after agent_submit_declaration_pdf or any upload that returned an index. It does not explicitly name alternatives or when-not conditions, but the triggering context is unambiguous.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuine value beyond them by naming the actual side effect — revocation of e-Factura synchronization for the CIF tied to the token — which an agent cannot infer from structured fields.

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

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

Three short sentences with no filler; the core action is front-loaded, the consequence second, and the parameter hint last. Every sentence carries distinct information.

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

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

For a single-parameter deletion with rich annotations and no output schema, this covers action, consequence, and parameter provenance. It could say more about failure modes (unknown ID, already-revoked token) but nothing essential is missing.

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

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

Schema coverage is 100% and the schema description already says 'integer ID from anaf_tokens', so the description's note about the integer ID and its source restates structured data rather than extending it. Baseline 3 is appropriate.

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

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

States a specific verb (delete) and resource (ANAF OAuth token), plus the concrete consequence for e-Factura sync. This distinguishes it cleanly from anaf_tokens (listing) and anaf_create_token_link (creation).

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 makes clear when you'd call it (to revoke e-Factura sync for a CIF) and tells you where the required ID comes from (anaf_tokens). It stops short of explicit exclusions such as what to do if the token is in use or how to re-establish access afterward.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds genuinely useful behavior: it is served from Storno's local mirror (implying cached/possibly non-live data) and is public with no account needed. Missing only whether the mirror has a refresh cadence or staleness caveat.

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 sentences: the first front-loads the resource and its two content axes with illustrative codes; the second covers sourcing and access. No filler, no restatement of the tool name.

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

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

For a zero-param lookup with no output schema, the description covers what is returned (county codes and their fiscal offices) and access conditions. It is slightly thin on return shape (flat list of counties with nested office arrays?) and on whether the whole nomenclator is returned at once.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly does not invent parameters and instead explains the shape of the returned data.

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

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

The description names the resource precisely and glosses the Romanian term ('cod judet as used in declaration XSDs'), plus concretely illustrates the payload with '40 = Municipiul Bucuresti, 13 = Constanta'. It also states the second content axis, fiscal offices (organe fiscale, ufisc codes). It does not differentiate from closely named siblings like anaf_nomenclator_localitati or anaf_nomenclator_strazi, so it stops short of 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?

'as used in declaration XSDs' implies the use case (filling county/office codes in declarations), and 'no account needed' removes a prerequisite. But there is no explicit when-to-use statement, no when-not, and no routing to the localitati/strazi nomenclators it sits beside in the sibling 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?

Annotations already cover the safe read-only, idempotent profile. The description adds genuinely useful context beyond them: the data is public (no auth) and served from a local mirror, which hints at possible staleness and avoids unnecessary auth attempts.

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

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

Two dense sentences front-load the resource and returned fields, then the filtering behavior. Nothing is wasted, though the parenthetical XSD reference makes the opening slightly heavy.

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

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

With no output schema, the description names the returned fields and clarifies locality vs county scope, which is enough for correct invocation. It could be more explicit about sibling choice, but no critical information is missing.

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

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

Schema coverage is 100%, but the description still adds meaning: it clarifies that q matches by name, is diacritics-insensitive, and gives concrete examples ('sector 6', 'cluj'), which the bare 'Name filter' schema description does not. County parameter semantics are left to the schema, which already has an example.

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 (locality nomenclator for a county) and names the exact fields returned (cod_localit, SIRUTA, town-hall codes), so its output is identifiable. Sibling differentiation is implicit rather than explicit, but 'locality' versus 'judete' and 'strazi' is clear enough from the name and first clause.

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

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

The use case is implied by 'as required by declaration XSDs, e.g. C168 cod_localit_L', which tells the agent when this data is needed. It does not say when to prefer this over anaf_nomenclator_judete or anaf_nomenclator_strazi, so the routing guidance is incomplete.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world. Beyond that the description adds real value: diacritics-insensitive prefix matching, local caching per locality, and public accessibility. No return-format or rate-limit details, but for a cached read-only lookup this is solid.

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

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

Two dense sentences, front-loaded with the tool's identity and return shape, followed by the filter semantics and caching note. Every clause carries information; no repetition of the title.

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

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

With no output schema, the description does supply the return shape (cod_strada + name), which matters. Required-vs-optional and the limit cap are left to the schema. For a simple read-only lookup it 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?

At 75% schema coverage the schema documents judet and localitate; the description adds the crucial semantics of q (word-prefix, diacritics-insensitive, with an example) and ties localitate to the naming/caching behaviour. The limit parameter remains undocumented in both places, 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?

States a specific resource (ANAF street nomenclator for a locality) with a concrete return shape (cod_strada + name) and an example value. This clearly distinguishes it from the sibling nomenclator tools (anaf_nomenclator_judete, anaf_nomenclator_localitati), which cover county and locality levels.

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 that streets are cached per locality on first use and marked public, and describes the q filter's prefix/diacritics behaviour, which tells an agent how to use it efficiently. It does not explicitly state that localitate must come from anaf_nomenclator_localitati (the schema carries that), nor state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful return behavior beyond annotations: token count, overall validity, and per-token CIF, expiry, and validity details. It does not explain open-world dependency behavior or rate limits, so it stops short of a 5.

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

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

Two sentences with no wasted text. The purpose is front-loaded, and the second sentence efficiently describes the return payload.

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

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

With no output schema, the description adequately explains what is returned for a zero-parameter read-only status check. It could be stronger by explicitly relating this overview to anaf_tokens and anaf_validate_cif, but it is otherwise complete for 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?

The tool has zero parameters, and the schema is empty, so there are no parameter semantics to document. Baseline for a zero-parameter tool is 4.

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: checking the current ANAF integration status for the authenticated user. It also previews the returned status data, but does not explicitly distinguish itself from sibling tools such as anaf_tokens or anaf_validate_cif.

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 “Check the current ANAF integration status,” so an agent can infer it is for status inspection. However, there is no explicit when-to-use guidance, no exclusions, and no named alternative for listing tokens or validating CIFs.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, but the description still adds real value: the hard cap of 50 entries (implying no pagination) and the enumerated status values (success, failed, skipped). Missing is any statement about ordering or whether the log is scoped to the caller's organization.

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

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

Two sentences, zero filler. The scope ('last 50 synced invoices') is front-loaded and the second sentence enumerates the return fields without restating the first.

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 input parameters and no output schema, the description carries the return-value burden and does so by naming the four fields and the status enum. Minor gaps: ordering of entries and whether results are org-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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline applies. The statement that it always returns the last 50 entries usefully explains why no filtering parameters exist.

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 ('Retrieve') and resource ('recent e-Factura sync activity log') with an explicit scope of the last 50 entries, plus the shape of each record. It does not, however, differentiate itself from nearby siblings such as anaf_sync_status or efactura_messages_list, which an agent must infer from names alone.

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

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

Usage is only implied: an agent can guess this is for inspecting what happened during ANAF e-Factura sync. There is no explicit 'use this when you need X, use anaf_sync_status instead when Y' and no stated prerequisites or failure conditions.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds useful transparency by naming the exact status information returned: sync enabled state, last successful sync timestamp, token validity, and sync frequency interval. It does not mention auth needs or company scoping, but for a read-only status tool this is relatively 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?

The description is two focused sentences with no wasted language. The purpose is front-loaded, and the second sentence efficiently lists the concrete return fields.

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

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

The description compensates for the absence of an output schema by listing the key returned fields, so an agent knows what information it will get. It is slightly incomplete because it does not clarify company scoping or how it relates to nearby ANAF status and sync-log tools.

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

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

There are zero parameters, and the schema is empty, so there is no parameter semantics to explain. The baseline for a parameterless tool is 4, and the description appropriately avoids inventing parameter details.

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

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

The description states a clear verb and resource: get current e-Factura synchronization status and configuration. It also enumerates the returned status fields, which makes the tool's scope concrete. It does not explicitly distinguish itself from siblings such as anaf_status, anaf_sync_log, or companies_toggle_sync, 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?

The description says what the tool retrieves but gives no guidance on when to use it versus related tools like anaf_status, anaf_sync_log, anaf_sync_trigger, or companies_toggle_sync. There are no exclusions or prerequisites, leaving the agent to infer usage from the name and purpose.

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

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

Annotations already declare non-read-only, non-idempotent, open-world and non-destructive, so the safety profile is covered. The description adds real value beyond that: it discloses the validation gates (token availability, subscription rate limits) and that the job is dispatched asynchronously to fetch invoices — behavior an agent cannot get from the annotations alone.

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

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

Two sentences, front-loaded with the action and scope, then the internal behavior. Every clause carries information; nothing is redundant or padded.

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

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

With no output schema, the description should indicate what the caller gets back. It says an async job is dispatched, which implies an immediate acknowledgement rather than results, but it does not point the agent to anaf_sync_status or anaf_sync_log for follow-up, leaving the post-call flow slightly incomplete.

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 schema is empty and fully covered. The description does add the meaningful semantic that the operation is unscoped — it applies to all companies with valid tokens — which is exactly the kind of information a parameterless tool needs.

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 (trigger) and resource (e-Factura/ANAF SPV sync) with an explicit scope: 'for all companies with valid ANAF tokens'. This scope implicitly separates it from per-client siblings like invoices_sync_client or companies_toggle_sync, but it never names an alternative, so an agent must infer the distinction.

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?

'Manually trigger' signals this is the on-demand path versus scheduled sync, which is useful implied guidance. However, there is no explicit statement of when to prefer this over anaf_sync_status, spv_sync_prepare, or invoices_sync_client, and no stated preconditions or exclusions beyond 'valid ANAF tokens'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond annotations by explaining what each token represents and what fields are returned (token ID, CIF, expiry, validity status); it does not contradict the annotations.

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 three sentences with no wasted language. It front-loads the primary purpose, then explains token meaning, then documents return fields in a natural order.

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 zero-parameter list tool with rich safety annotations and no output schema, the description is complete. It says what is listed, the scope, what a token represents, and which fields are returned, leaving no significant ambiguity for an agent.

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

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

The tool has zero parameters and the schema is empty, so the baseline is 4. The description does not need to compensate for parameter documentation and appropriately focuses on the resource and return fields instead.

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

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

The description states a specific verb ('List') and resource ('ANAF OAuth tokens') along with scope ('authenticated user') and business meaning ('enables e-Factura synchronization for a specific company CIF'). It does not explicitly name or differentiate itself from sibling tools such as anaf_status or anaf_create_token_link, which keeps it just below the top score.

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

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

The description implies usage by explaining that tokens enable e-Factura sync, so an agent can infer this is the tool to inspect existing tokens. However, it gives no explicit when-to-use guidance, no exclusions, and no mention of alternatives like anaf_create_token_link or anaf_delete_token.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered; the description adds genuine value by disclosing that external ANAF registry and permission lookups are performed and that failures surface as returned error messages rather than exceptions. It does not mention latency, rate limits, or auth prerequisites for those external calls, leaving some behavioral gaps.

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 with the core action front-loaded and the checks enumerated immediately after. No filler, though the trailing 'for a specific CIF' clause could be reworded to remove the parameter ambiguity without adding length.

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, read-only validation tool with full schema coverage and annotations, the description supplies what is missing: which external checks run and that error messages come back in the result. Without an output schema, a bit more on the shape of the validation result (boolean flag vs. structured error list) would make it complete.

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

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

Schema coverage is 100%, so the single parameter is fully documented as 'the ANAF token ID to validate' — baseline 3 applies. However the description's 'for a specific CIF' wording could send an agent looking for a CIF parameter that does not exist and does not explain that the CIF is derived from the token, which is a missed opportunity rather than a schema 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: validating that an ANAF token has e-Factura access, and names the three checks performed (organization ownership, ANAF registry, e-Factura permissions). It reads distinctly from siblings like anaf_tokens (listing) or anaf_status. The phrase 'for a specific CIF' slightly muddies it since the only input is a token ID, so it is not fully unambiguous.

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

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

Usage is only implied — an agent can infer this is a pre-flight check before submitting invoices via e-Factura. There is no explicit 'use this when...' statement, no mention of alternatives such as anaf_status or anaf_tokens, and no note about when this check is unnecessary.

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?

Goes beyond the readOnly/idempotent annotations by disclosing content details an agent would otherwise have to guess: revoked tokens are included, ordering is newest-first by creation date, and the raw secret is never returned (only tokenPrefix). Pagination or result limits are not mentioned.

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

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

Three short sentences, each front-loaded with new information (scope, contents/ordering, secret-safety). Nothing is repeated from the annotations or the 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 output schema, the description carries the burden of describing the return shape, and it does so well (active + revoked, sorted, tokenPrefix). Only pagination/volume behavior is missing, a minor gap for a list 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?

Zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies; the description correctly implies no filtering inputs are available.

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

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

States a specific verb and resource ('List all API tokens') plus scope ('for the authenticated user within the current organization'), which is enough for an agent to distinguish it from api_keys_scopes and the oauth2_clients_* 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?

Usage is implied by the name and the listing behavior, but there is no explicit 'use this when...' guidance, no mention of alternatives such as api_keys_scopes, and no prerequisites stated (e.g. admin role requirement).

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

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

The annotations already establish that this is a safe, read-only, idempotent, closed-world operation. The description adds meaningful behavior beyond that by noting that only scopes the user already holds are returned and that results are grouped by category.

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 two tight sentences with the core resource and filtering behavior front-loaded. There is no redundant or filler text.

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 parameters, no output schema, and rich annotations, the description is nearly complete: it states what is returned, how it is grouped, and that results are limited to held scopes. The main remaining gap is explicit differentiation from the similarly named OAuth client scopes 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?

The tool takes zero parameters, so there are no parameter semantics to explain. The empty schema and description are consistent, and the baseline for a no-parameter tool applies.

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

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

The description gives a specific verb and resource: list permission scopes for the current user, grouped by category. It is clear what the tool returns, but it does not explicitly distinguish itself from the similar sibling oauth2_clients_scopes or api_keys_list.

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 provides a clear usage context: inspecting what permissions a token can be granted. It does not state when to prefer it over sibling tools such as oauth2_clients_scopes, so it falls short of full alternative 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?

Adds substantial behavior beyond annotations: it always returns success to prevent user enumeration, the email is only sent if the account exists, and the reset link is valid for 1 hour. These are exactly the non-obvious operational traits an agent needs. The annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) are consistent with this description.

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 sentences, front-loaded with the action, followed immediately by the critical behavioral caveat about the always-success response and token validity. No wasted words.

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 one-parameter tool with no output schema, the description covers the essential behavior completely: what it does, why the response is always success, when the email is actually sent, and how long the link is valid. Nothing material 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?

Only one parameter (email) with 100% schema description coverage, so the schema already fully documents it. The description does not add syntax or format details beyond the schema, which is the expected baseline when schema coverage is high.

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: request a password reset email. It is distinguishable from the sibling auth_reset_password by implication (requesting the email vs performing the reset), but it does not explicitly name or contrast with that sibling.

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 purpose implies the usage context (a user forgot their password), but there is no explicit when-to-use guidance, no mention of the natural follow-up tool auth_reset_password, and 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?

The description adds important behavior beyond the annotations: it returns JWT access and refresh tokens, stores them in session config for subsequent requests, and establishes the authentication prerequisite. Since there is no output schema, this return-value context is especially valuable.

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 three focused sentences: purpose first, then return/session behavior, then the precondition. Every sentence contributes actionable information with 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?

For a two-parameter authentication tool with no output schema, the description covers what the tool does, what it returns, the session side effect, and when it must be called. That is sufficient for an agent to use 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?

The schema already fully documents both required parameters, including email format and password purpose. The description repeats email/password at a high level but adds no format, validation, or credential requirements beyond the schema.

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

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

The description gives a specific verb and resource: authenticate with the Storno.ro API using email and password. It clearly separates this from sibling auth tools by naming the credential type and the initial-token prerequisite, making it distinct from register, refresh, and profile operations.

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

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

It explicitly states when this tool is required: before any other tool if STORNO_TOKEN is not set. It does not name alternatives such as auth_refresh for expired tokens, so it stops short of full when/when-not/alternative 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond them by disclosing the response shape ('flat JSON with user, organization, memberships, and subscription'), which matters since no output schema exists. It stops short of saying what happens when unauthenticated (401/redirect), which would be the one remaining behavioral detail.

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

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

Two sentences, zero filler, with the identity purpose front-loaded and the return shape immediately after. Every clause carries information an agent would otherwise have to guess.

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-param read tool with full annotation coverage, the description supplies both purpose and return structure, and the absent output schema is compensated for. The only gap is the unauthenticated/error behavior, which is a minor omission given the tool's simplicity.

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

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

The tool takes zero parameters, so there is nothing to disambiguate; the baseline of 4 applies. The description correctly avoids inventing parameter guidance.

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 the current authenticated user profile' — and enumerates the included payload (organization memberships, subscription plan). This is unambiguously distinguishable from auth_update_profile, auth_login, and members_list 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?

Usage is implied by 'current authenticated user' — an agent can infer this is the identity/who-am-I call — but the description never states when to prefer it over members_list or companies_get, nor any preconditions. Adequate but leaves 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?

Goes meaningfully beyond the annotations: it discloses that both tokens are rotated (so the old refresh token becomes unusable and retries with it will fail) and that new tokens land in session config rather than being surfaced. That rotation detail is the single most important non-obvious behavior for this call. It stops short of describing failure modes (expired/revoked refresh token → re-login required).

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

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

Four short sentences, front-loaded with the action, then the side effect, then the storage location, then the trigger condition. No filler and no repetition of the tool name.

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

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

For a one-parameter auth tool with annotations covering the safety profile, this is nearly complete: action, rotation side effect, and storage destination are all covered. The only real gap is whether the new tokens are also returned in the response, which matters for an agent that needs to use them without relying on session state.

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

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

Schema coverage is 100% and the schema already explains that an omitted refreshToken falls back to STORNO_REFRESH_TOKEN. The description only says 'using the refresh token' and adds no format, precedence, or override semantics beyond what the schema states. Baseline 3 applies.

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

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

States a specific verb (refresh) and resource (expired JWT access token), plus the mechanism (refresh token). It is clearly distinct from auth_login and auth_me, though it never names those siblings explicitly, so the differentiation is implicit rather than stated.

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?

"Use when the current token has expired" gives a clear triggering condition, which is the main decision an agent faces here. It does not state the inverse case (e.g., when no refresh token exists, fall back to auth_login), so the alternative path 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?

Annotations already declare the mutation profile (readOnly=false, idempotent=false, destructive=false). The description adds genuine value beyond that: a default organization is created as a side effect and JWT tokens are returned on success — both important for an agent to know after a write. It does not say what happens on duplicate email or auth failures, leaving a small 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?

Three short sentences with zero filler, and the core action is front-loaded. The side-effect and return-value notes each earn their 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?

With no output schema, the description usefully states that JWT tokens come back and that an organization is provisioned, which is exactly the post-call context an agent needs. Error behavior (duplicate email, weak password) is left unstated, keeping it from a 5.

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

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

Schema description coverage is 100%, so the schema already documents email uniqueness, password minLength 8, and the optional name fields. The description adds no parameter-level detail beyond that, making the baseline 3 correct.

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 ('Create a new Storno.ro user account'), which clearly separates it from auth_login/auth_refresh/auth_me siblings. It stops short of naming which alternative an agent should choose when it already has credentials, so it is clear but not fully differentiated.

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

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

Usage is only implied by the verb 'create' – an agent can infer this is for new accounts rather than existing ones. It never states when to use auth_register vs auth_login or what to do if the user already exists, and there are no prerequisites or 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?

Goes beyond annotations by disclosing token lifetime (1 hour), single-use semantics, and the side effect of revoking all existing sessions on success — genuinely useful mutation context. Minor tension with idempotentHint=true since a second call with the same single-use token will fail, but the underlying end state is stable, so this is not a true contradiction.

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

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

Three short sentences, no redundancy, with the source of the token front-loaded and the consequences (expiry, session revocation) following. Every sentence carries a distinct piece of 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?

With no output schema, the description adequately explains the flow and side effects. It omits failure behavior (expired or already-used token) and whether authentication is required to call it, which would be useful for a credential-mutating endpoint.

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

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

Schema description coverage is 100%, so both 'token' and 'password' (with the 8-character minimum) are already documented. The description adds only the token's provenance, which is largely covered by the schema text; baseline 3 applies.

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

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

States a specific verb and resource ('Reset a user password') and explicitly ties the token origin to the sibling tool auth_forgot_password. An agent can distinguish it from auth_update_profile 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?

Makes the precondition clear: the tool requires a token obtained from auth_forgot_password via email. It does not explicitly exclude the other password-change sibling (auth_update_profile for logged-in users), so the when-not is only inferred.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the safety profile is covered externally. The description adds only the conditional requirement that currentPassword be supplied with password, which is already in the schema; it says nothing about whether omitted fields are preserved (partial update semantics), whether a password change invalidates sessions, or what permissions/auth state are required.

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

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

Two sentences, front-loaded with the action and object, followed by the updatable surface and the one conditional rule. Tight and readable, though the field enumeration duplicates schema content rather than adding new information.

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

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

For an 8-parameter mutation with a nested object and no output schema, the description covers what can be changed but not the important semantics: whether this is a partial or full replace, what happens to unlisted fields, or what is returned. Adequate as a pointer, incomplete as a contract.

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

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

Schema coverage is 100%, so every one of the 8 parameters is already documented, including the currentPassword/password pairing and the quiet-hours default. The description's field list largely restates the schema, and it says nothing about the nested preferences object's expected keys or merge behavior. Baseline 3 applies.

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

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

States a specific verb and resource: updating the authenticated user's own profile, and enumerates which fields can change. It implicitly disambiguates from members_update (other users) and notification_preferences_update, but never names those siblings explicitly, so an agent must infer the boundary.

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 phrase 'authenticated user's profile' implies it should be used for self-service edits rather than admin edits of other members. There is no explicit when-to-use/when-not guidance and no mention of the alternative tools, leaving the choice 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?

Annotations already declare this as a non-read-only, non-destructive, non-idempotent write, so the bar is lower, yet the description still adds real value: asynchronous processing, the full data scope (invoices, clients, products, settings), and the job-ID return contract. It omits what happens to previous backups or any retention/overwrite behavior, which for a non-idempotent create would be the remaining useful detail.

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

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

Three short sentences, front-loaded with the action, then scope, then return contract. Nothing is repeated and nothing extraneous is included.

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

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

With no output schema, the description correctly states what is returned (a job ID) and that processing is async, which is the key agent-facing fact. Minor gaps remain around retention, permissions, and interaction with existing backups, but nothing blocks a correct call.

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

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

Schema coverage is 100%, so both parameters are already documented; the description adds only the framing that files are optional, and its word "Optionally" is slightly at odds with the schema's default of true. It also describes the target as "the active company" without acknowledging the companyId override.

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

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

The description opens with a specific verb and resource ("Create a new backup job") and scopes it to the active company, with a parenthetical listing exactly what data is captured. It doesn't explicitly name the sibling tools (backup_status, backup_restore, backup_history), but the create semantics are unambiguous against them.

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

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

The line "Returns a job ID to check status" implies that backup_status is the follow-up tool, but the description never states when to create a backup versus when to use a restore or history tool, nor any prerequisites. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered; the description adds genuinely new context: the payload is base64-encoded binary data and the call fails unless the backup is completed. It does not mention size limits, expiry of the download link, or error behavior for non-completed backups, which would be the remaining useful detail.

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

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

Three short sentences with the action, the return format, and the precondition in that order. No filler, no restating of the tool name.

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

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

With no output schema, the description correctly takes on the return-value burden by stating the response is base64-encoded ZIP data, and it covers the blocking precondition. Minor gaps remain around how to poll for completed status and any size/encoding caveats, but an agent can call this correctly from what's given.

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

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

Schema description coverage is 100%, so both 'id' and 'companyId' are already documented in the schema. The description adds nothing about parameter semantics — notably it doesn't clarify whether 'id' is a backup job ID vs. an organization ID, or when to override companyId — so baseline 3 applies.

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

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

States a specific verb+resource ('Download a completed backup') and the artifact produced (ZIP file), which separates it cleanly from backup_create/backup_restore/backup_history in the sibling set. It stops short of naming backup_status as the companion call, so the differentiation is implied rather than explicit.

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 precondition — the backup must be in "completed" status — which is the key gating condition for calling this tool. It does not name the alternative tools (backup_status to poll, backup_history to locate a backup), leaving the routing to the agent's inference.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description does not need to repeat the safety profile. It adds real value with the 'active company' scoping and an explicit list of returned fields: job ID, status, creation date, file size, and whether files were included.

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

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

It is two sentences with zero waste. The core action and scope come first, and the return fields follow immediately.

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, read-only list tool with full schema coverage and strong annotations, this is nearly complete. It covers scope and return shape. The only minor gap is that ordering or recency semantics for 'recent' and the relationship to backup_status 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 100%, so both parameters, namely limit and companyId, are fully documented in the schema. The description reinforces the active-company default, but it adds no detail about limit behavior or result ordering beyond what the schema already provides.

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: it lists recent backup jobs for the active company. That is clearly distinguishable from backup_create, backup_restore, and backup_download, but it never explicitly says how it differs from the sibling backup_status, so it stops short of full sibling differentiation.

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 word 'List' and the phrase 'recent backup jobs' imply that this is the history-listing call, but the description never states when to choose this tool over backup_status or backup_download. The usage is inferable, not stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real value beyond them: async execution, the follow-up status tool, and the precise condition (purgeExisting=true) under which all company data is deleted. It stops short of stating whether the restore is reversible or which permissions are required.

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

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

Four short sentences, no filler, each carrying distinct information (action, async behavior, follow-up tool, destructive caveat). Placing the destructive warning last rather than first slightly weakens front-loading of the most critical fact.

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

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

With no output schema, the description should explain what the call returns so the agent can poll backup_restore_status (e.g., a job or backup identifier). It names the status tool but not how to use its result, leaving a meaningful gap for an async operation.

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

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

Schema coverage is 100%, so filePath, companyId, and purgeExisting are already documented. The description's warning about purgeExisting largely restates the schema's own 'Delete all existing company data before restoring' text, so it adds little new 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?

Names a specific verb+resource pair ('restore company data' from an uploaded backup ZIP), which is unambiguous against sibling tools like backup_create and backup_download. It does not explicitly contrast with those siblings, but the destructive restore semantics make the distinction obvious.

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 operating context: the restore is asynchronous and progress should be polled via backup_restore_status, which is the correct alternative tool for status. It lacks explicit exclusions (e.g., when to use backup_create instead, or prerequisites like a completed upload).

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds value beyond them by disclosing what is returned (progress percentage and current step) — important since no output schema exists. It stops short of describing terminal states or failure reporting.

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

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

Three short sentences, front-loaded with the action and followed by return content and sibling differentiation. Every sentence carries 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 a two-parameter read-only poll it covers action, return shape and sibling routing, and annotations carry the safety semantics. The one gap is how completion or failure is signaled, which matters given there is no 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 description coverage is 100%, with both `id` (restore job ID) and `companyId` (active-company override) documented in the schema. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource (get status of a restore job) and explicitly contrasts itself with the sibling backup_status, which is the closest confusion risk. It does not mention the backup_restore sibling that produces the job IDs, so routing is slightly less complete than it could be.

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?

"Same as backup_status but specifically for restore jobs" gives an explicit alternative and the condition that selects between them. It does not say when to poll versus wait, or whether the job is asynchronous, but the core use-vs-alternative guidance is present.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description still adds genuine value by disclosing the return payload (progress percentage, current step, download URL) and the full status lifecycle (pending, processing, completed, failed) — information the annotations cannot convey and that is essential for a polling 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 short sentences, zero filler, front-loaded with the core action and immediately followed by the return shape and status values. Nothing redundant with the name or title.

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

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

There is no output schema, so the description carries the return-value burden and does it well by naming the fields and enumerating statuses. It stops short of the one operational detail a polling tool needs — whether to re-invoke until 'completed' and whether backup_download should follow — but overall it is sufficient 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 100%, so both the backup job ID and the companyId override are documented in the schema. The description says nothing about either parameter and offers no syntax or format guidance; with full schema coverage the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Get the status of a backup job'), which is materially clearer than the bare name. However, it never distinguishes itself from the sibling status/read tools in this family (backup_history, backup_restore_status, backup_download), so an agent must infer which one to call for a given job type.

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 required job ID and by 'download URL when complete', which hints the agent should poll until completion and then fetch the artifact. There is no explicit when-to-use, when-not-to-use, or pointer to backup_restore_status/backup_history as alternatives, which matters given four similarly named backup 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior. The description adds valuable context beyond that: it explains data availability (trial-balance sections show hasData=false until balances are uploaded; aging, concentration, and profitTaxEstimate come from invoice data) and discloses limitations of profitTaxEstimate (information only, from invoices alone, real tax lower), plus the X-Company header requirement.

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 main purpose is front-loaded in the first sentence. However, the description is a single dense run-on sentence with semicolons that could be better structured into sections for readability. While the extensive enumeration is justified by the lack of an output schema, the delivery is not optimally concise.

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 the tool's complexity (many computed financial ratios) and the absence of an output schema, the description is remarkably complete. It covers all major output sections, caveats about data sources, the X-Company header requirement, and limitations of profitTaxEstimate. An agent has enough information to call 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 100%, so the schemas already document both parameters (year and companyId) with descriptions. The tool description adds no additional meaning about parameter formats, constraints, or behavior beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb (Get) and resource (balance analysis), and enumerates the returned indicators in detail. The purpose is unmistakable, but it does not explicitly contrast with sibling tools like balance_list or balance_rows, so it lacks sibling differentiation.

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

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

The description implies usage by stating it returns analysis for a year, but it offers no explicit when-to-use guidance, no when-not-to-use conditions, and no named alternatives. The prerequisite of X-Company header is noted but is not 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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description still adds real value beyond them by disclosing that this is a SOFT delete and that the parsed account rows are deleted alongside the balance — cascade and recoverability context an agent cannot get from the annotations.

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, zero filler, with the core action front-loaded and the cascade consequence immediately after 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?

For a two-parameter delete with no output schema and fully-covered annotations, the description supplies everything an agent needs: what is removed, that the removal is soft, and that dependent rows go with it. Nothing material is left unstated.

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

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

Schema description coverage is 100%, so both the id and companyId semantics (including the env-var override) are already documented in the schema. The description only echoes "by ID" and adds no format, scope or edge-case detail beyond that baseline.

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

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

States a specific verb and resource ("Delete an uploaded trial balance by ID") and scopes it to uploaded balances, which separates it from balance_list, balance_rows, balance_reprocess and balance_analysis by name alone. It does not explicitly contrast itself with any sibling, 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?

There is no when-to-use / when-not-to-use guidance and no alternative named (e.g., reprocess vs. delete-and-reupload). The phrase "uploaded trial balance" only weakly implies the precondition that the balance must already exist from an upload.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds some context by enumerating the status values (pending/processing/completed/failed) and returned fields, but says nothing about ordering, pagination, or how pending/processing uploads behave when listed.

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

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

Two sentences, both front-loaded with the essential fact (what is listed, what each entry shows). No filler and no repetition of schema content.

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

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

With no output schema, the description usefully compensates by naming the fields returned. It is nearly complete for a read-only list tool; only ordering/pagination behavior and the relationship to balance_rows are left unstated.

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

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

Schema coverage is 100% with only two parameters, so the baseline is 3. The description's phrase 'for a year' corroborates the required year parameter but adds no format or range detail, and it is silent on companyId (which the schema already documents as an env-var override).

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

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

States a specific verb and resource ('List uploaded trial balances') scoped to a year, and even names the returned fields. It does not, however, distinguish itself from close siblings like balance_rows or balance_analysis, so the agent must infer the boundary.

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

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

There is no explicit when-to-use statement, no prerequisites, and no routing to alternatives such as balance_rows (rows of a balance) or balance_analysis. The agent must guess that this is the enumeration/entry point versus the detail tool.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the actual side effect — the PDF is re-parsed and existing account rows are updated — which is more than the annotations say. It stops short of saying whether manually adjusted rows are overwritten, which is the main residual risk for 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?

Three short sentences, zero waste, with the operation stated first and the rationale last. Every sentence carries distinct information: action, mechanics, trigger.

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 2-parameter mutation with full schema coverage and no output schema, this covers what the tool does and why you'd run it. The one meaningful omission is what happens to previously edited or manually corrected account rows on reprocess, which the agent would want before invoking.

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

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

Schema description coverage is 100%, so both parameters (id, companyId) are already documented in the schema, including the env-var override behavior. The description contributes nothing about parameter meaning; baseline 3 applies.

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

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

Specific verb+resource: 'Reprocess a trial balance PDF', followed by the concrete mechanics ('re-parses the PDF file and updates the account rows'). An agent can distinguish this from balance_rows/balance_list (reads) and balance_delete without opening a schema, though it never names those siblings explicitly.

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

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

'Useful after parser improvements' gives a clear triggering condition for when to reach for this instead of a plain read. It does not state when NOT to use it (e.g. after manual row edits, or if the PDF is unavailable) or name an alternative tool.

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

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

Annotations already declare readOnlyHint/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond that by describing the payload shape (all account codes, names, and 10 debit/credit numeric columns), which is the only return-value documentation since no output schema exists. It omits any mention of row count limits or pagination.

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

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

Two sentences, front-loaded with the core action and followed by the return contents, with zero filler. 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 read-only, closed-world lookup with fully documented parameters, the description is nearly complete: it covers action, output contents, and a verification use case. The remaining gap is its relationship to the other balance_* tools and any row-volume caveats.

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

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

Schema coverage is 100%, with both id and companyId fully documented in the schema including the env-var override behavior. The description adds nothing about either parameter, so the baseline of 3 applies.

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

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

States a specific verb and resource: retrieves the parsed account rows of a trial balance, and even enumerates the returned fields. It does not, however, differentiate itself from nearby siblings like balance_list or balance_analysis, leaving the agent to infer that this is the raw-row view rather than the aggregate.

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?

"Useful for verifying PDF parsing results" implies a verification use case, but there is no explicit when-to-use vs. balance_analysis and no statement that the required id must first be obtained via balance_list. Usage is implied rather than stated.

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

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

Annotations only flag non-readOnly, non-idempotent, non-destructive. The description adds the non-obvious side effects an agent needs: per-company IBAN uniqueness, a hard limit of one cash account per company, openingBalance locking after set, and demotion of an existing default account for the same currency when isDefault is true.

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

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

Four tight sentences, front-loaded with the action, then the type-specific constraints, then the singleton cash rule, then the default-demotion side effect. No sentence is redundant with the schema or annotations.

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-param mutation with no output schema, the description covers the business invariants well, but it never says what the call returns (e.g., created account id) or whether any permission/role is required. Those are modest gaps rather than blockers.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds conditional meaning the schema states only per-field: IBAN required only for type=bank, and the default-demotion consequence of isDefault, which the schema's "Set as default account for this currency" does not convey. It leaves companyId override behavior and currency interaction to 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?

Opening sentence gives a precise verb+resource+scope: "Add a new bank account to the active company." The create semantics and the two account variants (bank vs cash) are unambiguous, so an agent can distinguish it from bank_accounts_update/list/delete 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?

The description clearly conditions usage on type: IBAN required for bank, optional for cash, and cash accounts exist to back POS/cash-register reports. It stops short of naming alternatives (e.g., bank_accounts_update for modifying an existing account) or stating exclusions, but the when-to-use context is 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?

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds real value beyond them by naming the two refusal conditions (last account, default account) and the side effect on invoices (IBAN retained in stored data). It does not say what error/sentinel is returned when deletion is blocked, nor whether any restore path exists.

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

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

Three short sentences, front-loaded with the action and its permanence, then the blocking rules, then the data-retention consequence. Nothing is repeated from the schema and no sentence is 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, the description covers the essentials an agent needs before mutating: irreversibility, two blocking conditions, and downstream effects on invoices. It stops short of documenting failure/error behavior and whether the deleted account can be recreated identically.

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

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

Schema description coverage is 100% for both parameters, so the uuid and companyId semantics are already carried by the schema. The description only gestures at company scoping ('for a company') and adds no format, identifier, or override detail beyond the structured fields.

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 ('Permanently delete a bank account') with the destructive permanence made explicit, which instantly separates it from bank_accounts_update/create/list. The added constraints and downstream data note further pin down its 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?

Gives clear preconditions and implicitly the alternative path: if the account is the default, 'set another as default first' (i.e., use bank_accounts_update). Missing an explicit statement of when to prefer a sibling such as listing accounts to verify, but the blocking conditions effectively define when-not-to-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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world. The description adds useful context beyond that: it specifies returned fields (IBAN, bank name, currency, default per currency) and business meaning ('appear on invoices as payment instructions'), which helps the agent understand the data's role.

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

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

Three short sentences, front-loaded with the action and scope, followed by return fields and business context. No filler or repetition.

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 read-only list with one optional parameter, no output schema, and rich annotations, the description is complete: it clarifies scope, returned fields, and domain relevance. Nothing essential 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 single parameter has 100% schema description coverage ('Company UUID override (uses active company if not set)'), so the schema carries the detail. The description's phrase 'active company' reinforces the default but adds no new syntax or format information.

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

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

States a specific verb and resource ('List all bank accounts') with clear scope: configured for the active company. An agent can immediately distinguish it from bank_accounts_create, update, and delete without needing 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?

Usage is implied by 'List all bank accounts configured for the active company', but the description does not explicitly say when to use this versus bank_accounts_create/update/delete or mention any exclusions. Adequate but not directive.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, so the safety bar is lower. The description still adds genuine behavioral value: the one-way lock on openingBalance once persisted >0 and the redirect of corrections to cash movements — a non-obvious irreversible-effect warning not captured by annotations.

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: purpose first, then the lock constraint, then the minimum-input rule. Every sentence carries decision-relevant information 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?

For a 9-parameter mutation tool with full schema coverage and no output schema, the description covers preconditions and the irreversible lock. It could note the return shape or confirm idempotent re-application semantics, but nothing critical to correct invocation 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 100%, so the schema already documents every parameter including the null-clearing semantics and the openingBalanceDate requirement. The description's field list largely restates the schema and adds little format/validation detail beyond it, so baseline 3 applies.

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

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

States a specific verb+resource ('Update an existing bank account') and enumerates the mutable fields (type, IBAN, bank name, currency, default status, opening balance), which lets an agent distinguish it from bank_accounts_create or cash_register_movements_update. It stops short of naming those siblings explicitly, so no explicit differentiation is given.

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?

'At least one field must be provided' gives a clear invocation precondition, and the statement that corrections must go through cash movements after openingBalance is locked effectively routes the agent to an alternative tool. It does not explicitly cover when to prefer create vs update or company-scoping choice, but the operational context is 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds that the payload contains supported banks and file formats, which is genuinely useful return context given there is no output schema, but it says nothing about whether the catalog is global or company-scoped despite the companyId parameter.

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

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

Two short sentences, front-loaded with the action and resource, with zero filler. The parenthetical gloss on 'borderou' earns its place by disambiguating a domain term.

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 trivial read-only catalog lookup with one optional parameter and no output schema, the description is nearly sufficient — only the company-scoping behavior of the result is unstated. Annotations carry the rest.

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

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

Schema description coverage is 100% and the single optional companyId is documented in the schema, so the baseline of 3 applies. The description does not mention companyId at all, adding no 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?

Uses a specific verb (List) plus resource (borderou/bank statement providers) and even decodes the domain term 'borderou' for readers. It distinguishes itself from the mutation siblings (borderou_upload, borderou_transactions_save) by being purely a catalog listing, though it never names those siblings explicitly.

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

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

The phrase 'for bank statement import and reconciliation' implies this is a discovery step before uploading or matching statements, but there is no explicit when-to-use statement, no prerequisites, and no named alternative among the many borderou_* 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that this is a filtered candidate-lookup, but says nothing about return size, pagination, or result caps that would matter for a search 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 sentences, front-loaded with the core action and purpose, with the searchable fields given second. No wasted words.

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

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

For a read-only lookup with fully documented schema and safety annotations, the description is sufficient to call it correctly. Missing only result-size/pagination expectations, which is a minor gap given the simple read-only nature.

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

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

Schema coverage is 100%, so all four parameters are already documented, including the type enum and companyId override. The description's 'search by number, client name, or amount' merely restates the search param description, adding no new semantics; baseline 3 applies.

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

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

States a specific verb (Get) and resource (invoices or proforma invoices available to match against a borderou transaction). The matching context distinguishes it from generic siblings like invoices_list and proforma_invoices_list, though it does not name those siblings directly.

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

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

The phrase 'available to match against a borderou transaction' implies the usage context (finding candidates during a borderou reconciliation), but there is no explicit when-to-use/when-not guidance and no named alternative such as invoices_list for general listing.

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

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

Annotations already declare this as a safe, idempotent, read-only, closed-world operation, so the description needn't cover safety. It does add useful response context by mentioning matched invoice/proforma details, but says nothing about error behavior, missing records, or company scoping effects.

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

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

A single front-loaded sentence with no filler. It is appropriately terse for a simple getter, though it could spend one more clause on the companyId override or return shape without becoming bloated.

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 read with full schema coverage and annotations covering safety, the description is nearly complete. The one gap is not explaining how the companyId override affects resolution, but that is minor given the schema documents 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?

Schema description coverage is 100%, so both the required id and optional companyId override are documented in the schema. The description adds no syntax or semantic detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (Get) and resource (a specific borderou transaction), and adds that it returns matched invoice/proforma details. The word 'specific' implicitly contrasts with the list-style sibling borderou_transactions, though no sibling is named explicitly.

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

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

Usage is only implied: an agent can infer this is for fetching one transaction by ID versus the list tool. There is no explicit when-to-use/when-not-to-use guidance or named alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds what the records represent (imported bank statement transactions with matching status, amounts, and linked invoice/proforma references), which is genuine value beyond annotations, but it says nothing about ordering, page-size limits, or total counts.

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

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

Two compact sentences, front-loaded with the operation and followed by what the records contain. Nothing is redundant, though the second sentence could be tightened into the first.

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

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

With no output schema, the description responsibly covers the returned record shape (status, amounts, linked invoice/proforma references). Combined with full schema parameter docs and read-only annotations, an agent has enough to call it correctly; only ordering/result-size behavior is left unstated.

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

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

Schema description coverage is 100% for all three parameters (page, limit, companyId), so the schema carries the semantics. 'With pagination' in the description only loosely corroborates page/limit and adds no format or constraint detail 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 ('List borderou transactions') and clarifies these are imported bank statement transactions, which distinguishes it from the singular borderou_transaction_get. It does not explicitly name a sibling, but the resource noun and 'List ... with pagination' make the collection-vs-single split reasonably obvious.

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 statement of when to use this versus borderou_transaction_get, borderou_transaction_update, or borderou_transactions_rematch. The only usage-adjacent hint is 'with pagination', which implies a paged listing but says nothing about prerequisites or alternatives.

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

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

Annotations already declare non-destructive, idempotent, closed-world behavior, so the description needn't repeat safety. It adds that the tool recomputes matches, but does not explain what happens to existing/manual matches or what is returned, leaving key side-effect detail unspecified.

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

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

Two short sentences, front-loaded with the action and followed by one useful trigger condition. No repetitive or irrelevant text.

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 2-parameter mutation, the description covers purpose and a usage scenario, while annotations and schema cover safety and parameters. It omits return/response behavior, which is not covered by an output schema, so it is nearly complete but not fully.

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