Storno CLI

Overview Schema Related Servers Score Discussions

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.17
Disambiguation2/5
While individual tools have detailed descriptions, there is significant overlap across document types. Invoices, proforma invoices, delivery notes, and receipts each have create/list/get/update/delete/issue/cancel/pdf/email/convert tool families that are structurally identical, making it difficult for an agent to quickly distinguish which document type to operate on. Additionally, tools like einvoice_config_save vs storage_config_update, backup_restore vs backup_restore_status, and the three invoices_export_*_saga_xml variants create boundary ambiguity despite detailed descriptions.
Naming Consistency4/5
Naming is overwhelmingly consistent, following the plural_noun_verb (e.g., invoices_list, clients_create) or domain_verb (e.g., anaf_sync_trigger) pattern. There are minor deviations: einvoice_config_list/save/delete/test vs storage_config_get/update/test vs mailer_config_get/update/delete use mixed list/get and save/update verbs across similar config resources. The invoices_export_*_saga_xml family also introduces inconsistency compared with the cleaner invoices_export_csv naming.
Tool Count1/5
283 tools is an extreme count for any single MCP server surface. Even accounting for a large invoicing/accounting platform, this represents an enormous surface that far exceeds the calibration guidance (extreme mismatch at 50+). While the complexity of the domain justifies many tools, 283 places an unreasonable cognitive load on an agent for tool selection.
Completeness4/5
The surface is remarkably comprehensive for the domain: full CRUD lifecycle coverage across invoices, proformas, delivery notes, receipts, clients, products, suppliers, VAT rates, bank accounts, document series, and recurring invoices, plus e-invoicing, e-Factura, ANAF, declarations, backups, imports, webhooks, notifications, memberships, licensing, and white-label features. Minor gaps exist (e.g., no receipts_events timeline mirroring invoices_events, no product delete/create since products are sync-only, no borderou delete/refresh beyond rematch), but these are defensible design decisions. The completeness is genuinely high despite the overwhelming count.
Average 3.9/5 across 283 of 283 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- No commit activity data available
- Last stable release on June 2, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under Elastic License 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does disclose the mutation behavior (creates payment records, updates invoice status), but doesn't disclose whether this is reversible, whether it can be called multiple times, whether it operates transactionally (all-or-nothing vs partial success), or what happens to already-paid invoices. For a persistence/save operation with zero annotation coverage, this is thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary purpose, minimal waste. Could arguably add a bit of behavioral context without bloating, but as written it's efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no annotations and no output schema. The description doesn't explain return values, error scenarios, idempotency, or whether the operation is atomic. Given it creates payment records and updates invoice status—a consequential financial operation—the description should provide more behavioral guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so schema documents both parameters. The description adds the meaning of transactionIds (matched transaction matches to save) and companyId context (active company fallback exists in schema). Baseline 3 is appropriate since the schema already carries the load, and the description adds limited extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool saves and persists selected borderou transaction matches, creating payment records and updating invoice payment status. The verb 'Save' plus resource 'borderou transaction matches' is specific, though it doesn't explicitly differentiate from sibling tools like borderou_transactions_rematch or borderou_transaction_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not state when to use this tool versus alternatives like borderou_transactions_rematch or borderou_transactions. It doesn't mention prerequisites (e.g., that matches must first be identified/loaded), nor does it explicitly exclude other tools or state what happens if called with unmatching IDs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided (no readOnlyHint, destructiveHint, or sideEffect), so the description carries the full burden. The description only mentions the return value (XML document as text) but does not disclose whether this is a pure export, whether it requires accounting export settings/preferences to be configured, whether it mutates any state (e.g., marking records as exported), or whether it checks for required conditions before exporting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence plus a return-type note. It front-loads the core purpose clearly without wasted words. Slightly more structure (separating purpose from return value) could aid parsing, but it's appropriately brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a clients export with no annotations, no output schema, and only a single optional parameter. The description is thin for an export operation — it doesn't mention what filter/criteria apply, whether deleted/inactive clients are excluded, expected prerequisites (e.g., configured Saga export settings), or how the returned XML text should be handled or saved. The sibling suppliers_export_saga_xml and various invoice Saga exports create ambiguity that the description doesn't resolve.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single companyId parameter, and the schema already explains it as a UUID override with default to active company. The description adds no parameter-level detail beyond the schema, which is acceptable given full coverage — baseline 3 applies. However, there's no guidance on what format companyId must take or interactions with the active-company selection mechanism.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it exports clients in Saga XML format for import into Saga accounting software, specifying the verb (export), resource (clients), format (Saga XML), and purpose (import into Saga software). It also notes the return type (XML as text). However, it doesn't distinguish from closely-related siblings like suppliers_export_saga_xml, invoices_export_saga_xml, and other Saga export variants beyond the resource type implicit in the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. Siblings include invoices_export_saga_xml, invoices_export_receipts_saga_xml, invoices_export_payments_saga_xml, and suppliers_export_saga_xml, all of which are Saga XML exports. Without stating when clients vs suppliers vs invoices export is appropriate or any caveats about required setup (e.g., accounting integration configuration), the agent must infer purpose from naming alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the output is base64-encoded XML compatible with SAGA import, which is useful. However, it doesn't disclose whether this is a read-only operation (export typically is, but not stated), whether it depends on company configuration, or whether there are size/scale limitations for large supplier counts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the core purpose and add the key output format detail. No wasted words. Could potentially mention more, but what's there is efficiently written.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and a single param, the description must carry more context. It fails to state whether this is destructive or safe, whether it requires setup (accounting export settings), how to use the returned base64 string (decode to file? buffer?), and any limitations. For an export tool whose result shape is entirely unknown to the agent, this is a meaningful gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single optional companyId parameter that has a clear description ('Company UUID (overrides configured default)'). The description mentions the default company concept implicitly through the parameter, adding minimal context but not materially supplementing the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Export) and resource (all suppliers) plus the target format (SAGA accounting XML). It distinguishes this from suppliers_export_csv clearly by format. However, it doesn't explicitly distinguish from clients_export_saga_xml or other saga exports beyond the resource type, which is implicitly clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives the output format ('base64-encoded XML file') but provides no guidance on when this should be used vs alternatives like suppliers_export_csv or the other SAGA XML export tools. No context about prerequisites (e.g., needing accounting settings configured) or when this is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the return is 'raw XML content' which adds some value, but doesn't disclose expectations about file size, whether the XML is already generated or requires generation, error scenarios (e.g., declaration not yet prepared), or any side effects (it's a read, but no confirmation). For an unannotated tool this is thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero wasted words. Efficiently conveys purpose and expected return type.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-required-param read tool with full schema coverage, the description is arguably sufficient at a basic level. However, the behavioral gap around whether the XML must already be generated (or if download triggers generation) and the relationship to declarations_prepare/declarations_agent_result aren't addressed. No output schema exists, so the 'raw XML content' note is helpful, but more on failure modes would strengthen it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema documents both parameters (id='Declaration UUID', companyId='Company UUID (overrides STORNO_COMPANY_ID env var)'). The description adds nothing beyond schema. With full schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Download') and resource ('generated XML for a tax declaration'), and notes the return type ('raw XML content'). It distinguishes from sibling declarations_get, which likely returns JSON metadata, and declarations_agent_result. However, it doesn't explicitly differentiate from other download-ish tools like exports_download or declarations_prepare.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says to download XML for a tax declaration but gives no guidance on when to use this versus declarations_get, declarations_validate, or declarations_prepare. There's no indication of prerequisites (e.g., must the declaration be generated/prepared first?) or when this tool would fail. No alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the link allows unauthenticated viewing and returns the share URL/token/expiry, which is somewhat informative. However, it doesn't disclose whether creation requires special permissions, whether links are revocable (though a revoke sibling exists), what the default expiry behavior means, or the security implications of creating an unauthenticated access link.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with zero waste. The description is efficiently front-loaded with the primary action ('Create a new shareable link for an invoice') followed by return values and link behavior. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation with good schema coverage and no output schema, the description covers the essential purpose and behavior. However, it lacks behavioral nuance about security implications of unauthenticated access links, permission requirements, or reversibility considerations. Given the tool's security-relevant nature (creating public access to a financial document), a bit more context would strengthen it. No output schema means the description's statement about returns helps, which it does cover.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all 3 parameters (uuid, companyId, expiryDays) are documented in the schema. The description adds value by clarifying the purpose (returns share URL, token, expiry date) but doesn't elaborate on parameter specifics beyond what the schema provides. The description does confirm the expiryDays defaults to 30, which aligns with the schema. Baseline 3 is appropriate since schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Create) and resource (shareable link for an invoice). It specifies what the link allows (viewing without authentication) and mentions the return values. It distinguishes from sibling tools like invoices_share_links_list and invoices_share_links_revoke through the 'Create' verb, though it doesn't explicitly name these alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the link does but provides no guidance on when to use this tool versus alternatives. There are related sibling tools (invoices_share_links_list, invoices_share_links_revoke) but no explicit comparison or when-not-to-use guidance. The auth-free viewing behavior is implied but no context on when sharing is appropriate vs sending email (invoices_email) is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It does disclose the soft-delete nature and that it cascades to parsed account rows, which is valuable behavioral context. However, it doesn't explain what 'soft-delete' means practically (e.g., whether the balance disappears from list views, whether rows are recoverable, audit implications). For a delete operation with no annotation coverage, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences that deliver clear value: the verb+resource statement plus the soft-delete cascade disclosure. Efficient and front-loaded. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a straightforward delete-with-id tool. The description plus 100% schema coverage covers the essentials. However, for a mutating operation with no annotations and no output schema, it could state what a successful delete returns (e.g., confirmation, deleted object, or empty). The soft-delete semantics are disclosed but the practical implications are left ambiguous. Adequate but with room to improve.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'id' (Trial balance UUID to delete) and 'companyId' (Company UUID overrides STORNO_COMPANY_ID env var) documented. The description adds the context that deletion cascades to parsed account rows, which is useful. Since schema already covers the parameters well, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete an uploaded trial balance by ID' with a specific verb+resource+scoping mechanism. It also discloses the soft-delete behavior ('soft-deletes the balance and its parsed account rows'), which distinguishes it from a hard delete. It doesn't explicitly contrast with siblings like balance_reprocess or balance_rows, but the delete action is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance about when to use this versus alternatives, or when one should prefer balance_delete over other trial balance operations. It doesn't mention any exclusions, prerequisites (e.g., whether balance must exist), or scenarios where deletion would be inappropriate (e.g., balances referenced by reports). No mention of irreversibility beyond soft-delete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description discloses it's a read/list operation and what fields it returns (status, month, account count, source software), which is helpful. However, it doesn't mention whether results are paginated, ordered, filtered by companyId, or what the exact response shape/size is. For a list operation with zero annotation coverage, this is a moderate gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The single-sentence description is efficient and front-loaded with the core purpose. It includes the relevant output fields in a parenthetical, which is compact. No fluff or repetition. It could be slightly more structured with the information it provides, but it's clean and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a straightforward list tool with 2 parameters (both documented in schema), no output schema required, and no nested objects, the description is moderately complete. It covers what the tool does and what it returns. However, for a read-oriented tool it doesn't mention potential statuses definitions, pagination, or result ordering, and the lack of annotations leaves some behavioral questions unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters (year and companyId) documented in the schema. The description adds the context that the tool lists by year and shows upload status, which complements the schema's year parameter meaning. However, the description doesn't add significant semantics beyond the schema - it mentions 'for a year' (matching the year param) but doesn't detail companyId behavior beyond what the schema's override note already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists uploaded trial balances for a year, with a specific verb+resource (list balances). It enumerates the fields shown (upload status, month, account count, source software), which adds specificity. However, it doesn't explicitly distinguish itself from the sibling 'balance_rows', 'balance_reprocess', or 'balance_delete' tools, so some ambiguity remains about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for viewing trial balances by year, which provides context for the 'year' parameter. However, there's no explicit guidance on when to use this vs alternatives, no mention of prerequisites (e.g., whether a company must be selected), and no exclusion criteria. The context is clear but there are no explicit when/when-not statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not state whether this is a read-only operation (implied by 'Get' but not confirmed), whether it requires permissions, or what fields of enrichment it returns vs the list version. However, the description does disclose the scope of returned content (line items, client, deputy, totals), which adds some value over the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose, and efficiently enumerates the return scope. No wasted words, though it could arguably add a usage-context note. Appropriate length for this tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward get-by-id tool with 100% schema coverage and no output schema, this is adequate. However, no annotations exist and there's no behavioral disclosure about permissions or return format. Given sibling context (there's a delivery_notes_get vs list and many get tools), a note on return richness vs list could help. But for the tool's simplicity, this is minimally sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (uuid, companyId) documented in the schema. The description adds the enrichment context (what data comes back), which builds on the uuid parameter's meaning. Since coverage is high, baseline 3 is appropriate; the description doesn't add syntax or format details beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb+resource ('Get complete details for a specific delivery note') and enumerates what's included (line items, client info, deputy details, calculated totals). It distinguishes from the sibling 'delivery_notes_list' by being the 'get by uuid/details' variant, though it doesn't explicitly name the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as a detail-retrieval operation for a specific delivery note but doesn't explicitly state when to use it vs alternatives like delivery_notes_list or get for other document types (invoices_get, receipts_get). No exclusions or when-not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It clearly discloses this is a read-only status/get operation, which implies no side effects. It discloses what fields are returned (progress, row counts, error details). However, it doesn't address whether results are cached, whether the job must complete first, or what happens if the job ID doesn't exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that conveys the purpose and key output fields efficiently. No wasted words, though it could arguably be split for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id read operation with only 2 well-documented parameters and no output schema, the description adequately covers the essentials. However, given the large set of import-related siblings, some pointer to related workflows (when to call this in the import lifecycle) would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters documented ('Import job ID' and 'Company UUID override'). The description doesn't add meaningful semantic depth beyond the schema, but the schema itself is adequate. Baseline 3 applies since the schema handles documentation well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the full status and details of an import job, enumerating specific content (progress, row counts for imported/skipped/failed, error details). This is a specific verb+resource with concrete detail, though it doesn't explicitly distinguish from sibling import tools by naming alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus import_preview, import_execute, import_history, or other import-related siblings. The description gives no context about when to poll this tool (e.g., after execute, during long-running jobs) or when an alternative would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It doesn't state whether this is a read-only operation (though 'Search' implies it), doesn't describe return format, whether partial matches are supported, case sensitivity, or pagination behavior beyond what the limit parameter implies. For a search tool with no annotations, this is a modest gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact two-sentence structure, front-loaded with the core purpose and followed by domain context and expected return. No wasted words, though it could potentially be trimmed further given the schema already covers parameter details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter search tool with no output schema, the description is reasonably adequate. It conveys purpose, the classification system (NC/NACE), use case (e-Transport), and returns matching codes. However, it doesn't clarify whether results include hierarchical parent/sibling codes, how matching works (exact vs fuzzy), or any limits on the search more explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters ('search' as code number or description text, 'limit' with max/default) are already documented in the schema. The description reinforces that search accepts 'code number or description text' which adds slight value but largely mirrors the schema. Baseline 3 is appropriate given complete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb+resource ('Search NC classification codes') and the domain context (e-Transport declarations for goods classification). It distinguishes from siblings by specifying the NC code type, though there is a sibling 'cpv_codes_search' which shares a similar search pattern and could have been explicitly contrasted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context ('used in e-Transport declarations for goods classification') but does not give explicit when-to-use/when-not-to-use guidance. It doesn't mention alternatives like cpv_codes_search or distinguish from other product/code lookup tools, though the NC-specific context offers implied usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description only states the company-scoping trait. It does not disclose that invalid color values are silently dropped (which appears in the schema parameter description but not the main description), permission/authentication requirements, whether duplicate names are rejected or allowed, or what the response looks like (no output schema). For a create/mutation tool, this is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero filler. It efficiently conveys the resource and the scoping constraint. It could arguably add a bit more behavioral context without becoming verbose, but as written it is appropriately sized and waste-free.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with a 4-param schema that is 100% covered, the missing elements are behavioral: no output/return description (no output schema exists so the description should explain what's returned, e.g., the created category object), no note about duplicate-name handling, and no mention of required permissions. Given no annotations and no output schema, the description is somewhat thin for a mutation operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 4 parameters (name, color, companyId, sortOrder) are documented in the schema. The description adds marginal value by noting company scoping ties companyId to the active company, but it doesn't elaborate on the name validation (1-100 chars), color hex format, or sortOrder semantics beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Create) and resource (a new POS product category), and adds the scoping detail ('Categories are scoped to a single company') which is useful. It distinguishes from siblings like product_categories_update/delete/list adequately via the create verb, though it doesn't explicitly differentiate from other create tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the company scoping constraint, which conveys context about how the companyId parameter relates to the active company. However, it provides no guidance on when to use this vs. browsing existing categories first (product_categories_list), no mention of potential duplicate-name behavior, and no when-not-to-use guidance. The context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states this is a read-only get operation that returns pre-filled content, which is good, but it doesn't disclose details like whether the default recipient comes from the company config, whether substitutions can fail, or what happens when the uuid is invalid. Has no output schema to compensate for missing return-type documentation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that efficiently captures the purpose and key output content. It's concise without being under-specified; the sentence is front-loaded with the active verb 'Get' and specifies the resource. Could arguably include usage guidance but the sentence itself is well-paced.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a straightforward read-only retrieval tool with only 2 parameters, both schema-documented. Given its simplicity, the description covers the core purpose adequately. However, it doesn't mention return format, which matters since there's no output schema, and an agent can't know what keys to expect (recipient, subject, body). Also could clarify the relationship to receipts_email for sending context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters are documented in the schema (uuid as receipt identifier, companyId as override). The description adds the concept of 'template variables already substituted' but doesn't explain how the two params interact beyond what schema says. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves pre-filled email content for a receipt, including recipient, subject, and body with template variables substituted. It distinguishes from the sibling receipts_email (which sends) and receipts_email_history, though it doesn't explicitly differentiate from those.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for retrieving default email content before possibly sending via receipts_email, but it doesn't explicitly state when to use this versus alternatives. The context of 'receipts_email_defaults' alongside 'receipts_email' and 'receipts_email_history' makes the intent somewhat clear but no explicit guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. The description mentions 'selected company' implying a default company context with optional companyId override, and states receipts 'can be converted to invoices' as a behavioral capability. However, it doesn't disclose pagination behavior, response format, or the fact that creating/issuing/canceling receipts would be handled by other sibling tools. For a read/list operation with zero annotation coverage, it should disclose more behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-structured sentence that introduces the tool's purpose, lists filtering capabilities, and adds one useful behavioral note (convertible to invoices). It's efficient and front-loaded with the primary purpose. No wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 parameters with full schema coverage, making it moderately complex. There's no output schema, so the description somewhat should hint at return content. The description covers filtering options and conversion capability but doesn't indicate what fields are returned (receipt number, amounts, client info) or pagination defaults beyond what's in the schema. For a list tool with no output schema, this is adequate but could be more complete about the returned data shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 8 parameters with clear descriptions for each (date range, page, limit, search, status enum, clientId, companyId). The description adds a bit beyond schema by framing filters ('status, date range, client, search term') and noting the company context concept ('selected company' vs 'overrides configured default' in schema). But the schema already carries the semantic weight, so the description adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this tool lists receipts (bonuri fiscale) for a selected company with filtering options. It distinguishes its purpose from invoice listing tools by specifying receipts as point-of-sale transactions, which is a distinct resource type. While it doesn't explicitly differentiate from siblings like receipts_get or receipts_create, the action 'list' with filter context makes the purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it lists receipts for the selected company with optional filtering, implying usage when one needs to retrieve receipt records. It notes receipts can be converted to invoices, which suggests a context for use. However, it doesn't explicitly state when NOT to use this tool versus alternatives like receipts_get (single receipt retrieval) or invoices_list (if the user wants invoices instead), leaving the decision partially implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description states it returns counts and errors for failed items, which is some transparency about partial-failure behavior. However, it's a destructive operation with zero annotation coverage—it doesn't disclose irreversibility, whether deletion is permanent or soft (restorable), whether related data is affected, or any 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, direct and efficient. The description front-loads the action and resource in the first phrase, and the second sentence adds useful detail about the return value. No filler or redundancy. Slightly more behavioral detail could be added but the structure itself is well-executed for a destructive bulk operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a destructive bulk operation with no annotations and no output schema, so the description carries significant burden. It covers the basic purpose and return behavior (count + errors), but lacks detail on irreversibility, whether existing recurring invoice schedules based on these templates are affected, or how companyId scoping interacts with deletion. For a destructive bulk operation, this could reasonably be more thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'ids' (array of UUIDs 1-100) and 'companyId' (overrides configured default) documented. The schema explicitly describes constraints like min/max items and the company override semantics. The description adds marginal value by confirming the 'ids' array is what gets deleted, but the schema already does the heavy lifting, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes multiple recurring invoice templates in a single request, with a specific verb (delete) and resource (recurring invoice templates). It distinguishes from the singular recurring_invoices_delete sibling by noting 'multiple' and 'bulk'. However, it doesn't explicitly distinguish from other bulk operations likes recurring_invoices_bulk_toggle_active or recurring_invoices_bulk_issue_now, but the verb 'delete' clearly separates them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies bulk deletion use case by stating 'in a single request' and mentions returning counts and errors for failed items, which conveys batch-processing context. However, it doesn't explicitly state when to choose this vs the singular recurring_invoices_delete, nor does it mention any irreversibility warning or confirmation requirements that one might expect with bulk destructive operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states it lists templates for the selected company and supports filtering, but doesn't describe pagination behavior, what fields are returned, whether both active and inactive are shown by default, ordering, or scope semantics of the 'selected company' default that companyId overrides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose. Compact and efficient. Could mention pagination ordering or toggle behavior but doesn't pad with unnecessary content. Appropriate length for a list-type tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 6 optional params and no output schema, this is reasonably complete. It documents the filtering dimensions (status, frequency) and implicitly pagination via schema params. Missing: default ordering, whether inactive templates are hidden by default, what 'selected company' means, and any return-field guidance. No output schema means the description should note return shape, which it doesn't.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (page, limit, search, isActive, companyId, frequency) having a description. The description adds the frequency and isActive filter capabilities explicitly, but doesn't add semantic detail beyond the schema. Baseline 3 applies given full schema coverage. The frequency enum values are self-documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb (list) + resource (recurring invoice templates) + scope (selected company). It distinguishes from siblings like recurring_invoices_get/create/update/delete by framing this as the list/listing operation. However, it doesn't explicitly contrast with any sibling beyond the name difference, 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description doesn't specify when to use this vs alternatives, nor exclusions. It mentions the selected company scope implicitly, which gives some context. Siblings like recurring_invoices_get exist for single-template lookup but no explicit when/when-not guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It reveals the report nature (read-only analysis) and the X-Company header requirement, which is helpful. But it doesn't disclose whether the tool mutates any state, performance/size limits (e.g., large date range behavior), auth scopes needed, or what happens with invalid company context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise paragraph that front-loads the core purpose before enumerating outputs. Every sentence earns its place — the report contents list and the company header note both add value. Slightly dense but no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only reporting tool with 100% schema coverage and no output schema, the description reasonably covers inputs and expected outputs. However, without annotations and with no guidance on date-range limits, large result handling, or subtleties of the KPI calculations, it leaves room for ambiguity in edge cases. Adequate for a straightforward report tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (dateFrom, dateTo, companyId) are documented in the schema. The description adds context by explaining that companyId overrides the STORNO_COMPANY_ID env var, which is a meaningful relationship detail beyond the schema. The date format guidance lives in the schema, so the description compensates adequately though not richly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear verb-resource combination ('Generate a sales analysis report') with an explicit date range scope and enumerates the returned content (KPI summary, monthly trends, invoices, top clients, products). This clearly distinguishes it from other reporting tools like reports_vat and generic list endpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it requires the X-Company header (companyId or env var), which is useful setup context. However, it gives no guidance on when to use this tool versus alternatives like reports_vat, invoices_list, or balance_list, and provides no exclusion criteria or prerequisite conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies an idempotent re-computation operation but does not disclose what happens to existing matches, whether prior manual matches are overwritten, or whether the tool mutates state. For a rematch operation that likely modifies matching outcomes, this is a notable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, zero wasted words. The first states the action and target; the second provides a usage trigger. Front-loaded and efficient with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter mutation tool with full schema coverage but no annotations and no output schema, the description covers the basic what and when. However, it lacks behavioral details about the rematch's effect on existing matches, which is significant for a tool that re-runs an algorithm potentially destructively. Adequate but with a clear gap around side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (transactionIds and companyId) are documented in the schema. The description adds the context that companyId is an override and that transactionIds are the targets of the rematch, but doesn't materially add semantics beyond the schema. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Re-run), resource (automatic matching algorithm), and scope (selected borderou transactions). It's distinguishable among siblings like borderou_upload and borderou_transactions_save, though it doesn't explicitly reference those sibling names. The purpose is specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use context ('Useful after adding new invoices or updating client data'), which gives a reasonable trigger for invocation. However, it doesn't mention when NOT to use it or suggest alternatives among the borderou siblings (borderou_transactions_save vs rematch). The guidance relies on the reader inferring the distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It does note that output is base64-encoded binary data, which is useful. However, it doesn't mention whether this is a read-only operation, whether pagination/limits apply to large client sets, or whether the export is synchronous or async (potentially requiring the exports_download tool). The limitation on client count or file size is not disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with zero waste. It front-loads the core purpose, then adds one behavioral detail (base64 encoding). Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter export tool, the description is mostly adequate. However, there are gaps: it doesn't clarify whether the export is synchronous or returns immediately with all data, whether there are size limits on the resulting base64 string, which fields are included in the CSV, or how it relates to the exports_download tool. With no output schema to clarify the return structure, a bit more detail about the response would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — the only parameter (companyId) is documented in the schema as 'Company UUID override (uses active company if not set)'. The description adds nothing beyond the schema's parameter documentation. The description does reinforce the 'active company' concept but doesn't add meaningful new semantic detail about the parameter beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Export), resource (all clients for active company), and output format (CSV file). It distinguishes reasonably from clients_export_saga_xml and other CSV exports (suppliers_export_csv) by specifying it's client data. However, it doesn't explicitly differentiate itself from the sibling clients_export_saga_xml though the format (CSV vs saga XML) makes it fairly obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like clients_export_saga_xml, clients_list, or exports_download. It mentions it returns base64-encoded data rather than writing to a file, but there's no explanation of when a user would want CSV vs other export formats, nor mention of the (likely) exports_download tool for fetching results of async exports.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It reveals that this tool returns XML, ANAF URL, Bearer token, and CIF needed by a 'local agent' to proxy an mTLS request. However, it doesn't disclose behaviors like whether this mutates state, whether there are auth/authorization requirements, rate limits, whether the Bearer token is sensitive/expires, or what happens if called without the agent. The 'prepare' wording implies a non-submitting preparation step, but the exact side effects are unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and reasonably front-loaded with the core purpose. The return-value list and operation-param mapping are packed efficiently. One could argue the return values list could be slightly expanded for clarity on shape, but overall it's tight and waste-free.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 params, 100% schema coverage, no output schema, and no annotations, the description covers the purpose, flows, and return values adequately but not richly. The multi-flow nature (submit/listMessages/download) and the agent-proxy mechanics are non-trivial, and the description does a decent job introducing them. However, without an output schema, the return structure (XML content, URL, token, CIF) is only hinted at rather than fully specified, which is a meaningful gap for a tool whose entire output is consumed by an external agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents all parameters well. The description adds value by explaining how the operation param drives flow selection and that downloadId is required for operation=download. It also clarifies that companyId overrides an env var. This adds meaningful context beyond the bare schema definitions, though it doesn't detail the exact format of id (UUID) or companyId beyond what schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Prepare a declaration for agent-based submission.' It specifies the verb (prepare), resource (declaration), and the specific goal (agent-based submission). It then lists the return values (XML content, ANAF URL, Bearer token, CIF) and the operation flows. However, it doesn't explicitly distinguish itself from siblings like declarations_submit or declarations_agent_result, though the agent-based proxy nature is implied and somewhat differentiating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the operation param with its three flows (submit, listMessages, download) and notes the defaults, but does not explicitly state when to use this vs alternatives like declarations_submit or declarations_agent_result. The agent-based proxy aspect is the distinguishing factor but is not framed as 'use this when...' guidance. No explicit exclusions or alternative tool recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries full burden for behavioral disclosure. It mentions status values (active/revoked/expired) which is useful, but it does not indicate whether this is a pure read operation, return ordering, filtering, pagination, or whether revoked/expired links are listed by default or require flags. For a list tool with no annotation safety profile, this is a meaningful gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence frontloads the verb, resource, and returned fields with zero redundancy. Every element earns its place; status values are compactly enumerated. Excellent structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward list operation with 2 well-documented schema parameters, so the description covers the core purpose. However, there is no output schema and no annotations, so the description should do more to clarify return-shape details (e.g., whether only non-expired links are shown, how view counts are aggregated, whether the list is paginated). For a moderately simple list tool this is adequate but not enriched.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% at the parameter level—both uuid and companyId have descriptions. However, the description adds no value on top: it doesn't explain the relationship between uuid and companyId, that companyId is an override, or detail how these parameters shape the returned links. The description adds no semantics beyond what the schema already declares, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('all share links for an invoice') and enumerates what data is returned (view counts, expiry info, status). It clearly distinguishes from siblings like invoices_share_links_create and invoices_share_links_revoke, which are operational actions rather than listing. A clear 4, though it doesn't explicitly name its sibling alternatives as competing read tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a read-only listing use case but provides no explicit when-to-use guidance or exclusions. Context signals like 'required: uuid' suggest you need an existing invoice's UUID, which is implied but not stated. No alternative tool is named as an alternative, and it's not clear how this differs from other list operations in the suite for a non-obvious case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It does explain the toggling behavior and its side effect (enabling/disabling automatic invoice generation), which is useful. However, it doesn't disclose the state-transition nature beyond the immediate toggle, potential consequences of pausing (e.g., affecting scheduled generation), reversibility, or the return value/confirmation response after the call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, the first states exactly what it does with the toggle verb and resource, the second clarifies the bidirectional behavior. Zero waste, fully front-loaded with the outcome stated first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple 2-param, single-required-param tool with no output schema or nested objects, so the burden is modest. The description covers the core behavior and effect. However, with no annotations and no explicit return-value or confirmation info, and the existence of a bulk_toggle_active sibling, a slightly richer statement about the response or how to verify success would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters (uuid and companyId) documented in the schema. The description adds no additional parameter-level detail beyond what the schema states. The description mentions 'active status' conceptually but adds no new parameter context, landing at the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool toggles the active status of a recurring invoice template to pause or resume automatic generation, with a specific verb (toggle) and resource (recurring invoice template active status). It distinguishes from siblings like recurring_invoices_update/delete and bulk_toggle_active through the single-template toggle scope, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the effect (pause if active, resume if paused) giving operational context, but does not explicitly state when to use this vs the bulk_toggle_active sibling, nor mention any prerequisites like ownership or company selection. Usage context is implied but not fully articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. 'List' implies a read operation, and the description lists return fields, but it says nothing about pagination behavior beyond limit, ordering (which field sorts results), whether results are limited to a window, or any side effects. As a historical/job-listing tool with no annotations, this is a meaningful gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The description is front-loaded with the primary purpose and then enumerates return fields efficiently. Reasonably concise, though it could be considered slightly thin given the number of behavioral aspects it omits.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only 2 parameters with 100% schema coverage, no output schema, and no nested objects, so complexity is low. The description adequately covers purpose and return fields. However, for a backup-history listing tool with no annotations, it lacks details on ordering/sorting of jobs, default scope, and whether results are scoped by time window — minor completeness gaps for an otherwise simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (limit, companyId) are fully documented in the schema itself. The description adds the 'active company' concept that contextualizes the companyId override, but doesn't explain the limit semantics beyond what the schema's max/default already provide. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('recent backup jobs for the active company') and explicitly enumerates the return fields (job ID, status, creation date, file size, file inclusion). It clearly distinguishes from sibling tools like backup_create, backup_status, and backup_restore, which are different operations on the same domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it lists jobs 'for the active company', which provides context on scope, but offers no explicit when-to-use guidance or exclusions distinguishing it from backup_status or backup_restore_status. It implies read-only usage but doesn't provide alternative tool recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that it 'Re-parses the PDF file and updates the account rows,' which reveals the destructive/updating nature. However, it doesn't clarify whether the reprocessing overwrites existing rows, whether it's reversible, what happens to previously manually-edited rows, or what the return value looks like. Half of the burden is met.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero wasted words. States what it does, the mechanism, and the use case. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a reprocessing/mutation tool with no output schema and no annotations, the description provides a basic understanding of purpose and use-case trigger. However, it lacks detail on side effects, data loss risk, permissions needed, or what happens to previously extracted/modified data. The complexity is moderate (a reprocessing action on financial data), and given the absence of annotations, more behavioral context would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are documented with descriptions ('Trial balance UUID to reprocess' and 'Company UUID (overrides STORNO_COMPANY_ID env var)'). The description adds the context that companyId overrides an environment variable, which is useful. However, the parameter descriptions are relatively minimal and the tool description itself doesn't elaborate on parameter usage beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Reprocess a trial balance PDF. Re-parses the PDF file and updates the account rows.' This uses a specific verb (reprocess/re-parse) and resource (trial balance PDF). It distinguishes from siblings like balance_list and balance_rows by focusing on the parsing/reprocessing action, though it doesn't explicitly name sibling alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it's 'Useful after parser improvements,' which implies the context where it should be used (after a parser update to re-extract data). However, it doesn't explicitly state when NOT to use it or name alternative tools. The guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description only mentions what data is returned ('matched invoice/proforma details') but does not state whether this is a read-only safe operation, whether it requires permissions, what happens if the transaction is not found, or any rate-limit concerns. For a get operation with no annotation coverage, some transparency about safety/read-only nature would be expected, though 'Get detailed information' implicitly signals a read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that states the core purpose concisely without extraneous words or filler. It front-loads the primary action ('Get detailed information') and adds the key distinguishing detail (matched invoice/proforma details). However, it misses opportunities to add sibling differentiation or usage context in the available space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 2 parameters at 100% schema coverage, no output schema, and a straightforward 'get by id' operation, the description conveys the tool's scope adequately. The sibling tools include borderou_transactions (list), borderou_transaction_update, and borderou_transactions_save, so the purpose is reasonably clear. However, no output schema exists to explain the return shape, and the description does not mention the companion tool borderou_transaction_available_invoices or how this differs from other borderou retrieval paths.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — both 'id' and 'companyId' have descriptions ('Transaction ID' and 'Company UUID override...'). The description itself does not add parameter-level meaning beyond what the schema provides, which is acceptable given full coverage. The baseline 3 applies since the schema carries the documentation weight and the description doesn't add extra semantic detail about the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and a clear resource ('specific borderou transaction') and adds the distinguishing feature of including 'matched invoice/proforma details'. This clearly differentiates it from sibling tools like borderou_transactions (list) and borderou_transaction_update. It distinguishes its purpose effectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide when-to-use guidance or explicitly distinguish from alternatives like borderou_transactions or borderou_transaction_available_invoices. The purpose is implied to be retrieving a single transaction's detail, but there is no explicit statement of when to choose this tool over the list or update variants, and no stated exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the disclosure burden. It mentions the returned data characteristics (matching status, amounts, linked invoice/proforma references) and pagination behavior, which is useful. However, it doesn't describe the response format, whether results are sorted, or any filtering behavior beyond pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with a useful second sentence about returned data. There's no wasted text and the key purpose is front-loaded (lists + pagination first). It could arguably add a bit more but remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a list operation with three well-documented parameters, the description is reasonably adequate. There's no output schema, so describing the return type is helpful and partially done (matching status, amounts, linked references). However, it doesn't cover whether items are ordered by date, how many results to expect, or whether pagination is cursor- or offset-based.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all three parameters (page, limit, companyId). The description adds that companyId overrides the active company, but this is already in the schema. The description's mention of 'matching status' implies some filtering but doesn't clarify how status filtering works or which parameters control it, since none of the three params relate to status.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists borderou transactions with pagination, and specifies the returned data includes imported bank statement transactions with matching status, amounts, and linked invoice/proforma references. It distinguishes itself from siblings like borderou_transaction_get (singular fetch) and borderou_transactions_save/rematch (operations), though it doesn't explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a list/listing operation for borderou transactions, but provides no explicit when-to-use guidance or alternatives. It doesn't name sibling tools like borderou_transactions_rematch or borderou_transaction_available_invoices, nor does it explain when pagination is needed or what the default behavior covers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It meaningfully discloses the destructive behavior (deletion) and the conditional behavior around clients with existing documents ('skipped or cause an error depending on server configuration'). This is important behavioral context. However, it doesn't disclose whether deletion is reversible, what authorization/permissions are needed, or the response format/status codes that might result from partial failures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and front-loaded, with the primary purpose and constraint stated first. The conditional behavioral note in the second sentence is important and earned. No wasted words, though the ambiguity in the second sentence ('skipped or cause an error') could be considered slightly more verbose than ideal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a batch mutation tool with a 100-item limit and conditional behavior around documents, the description covers the core mechanics but leaves gaps: it doesn't clarify the outcome for the ambiguous 'skipped or cause an error' condition (which is configuration-dependent), doesn't state whether the operation is atomic or partial-commit, and doesn't describe what happens with invalid UUIDs mixed into a valid batch. No output schema exists to fill these gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (ids as UUID array max 100, companyId as optional override). The description adds the UUID requirement to the description text but largely repeats what the schema covers. It doesn't add meaning about id format validation, how errors map to specific ids, or behavior when some ids are invalid while others are valid.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete multiple clients in a single request') with a specific verb and resource. It adds useful scope details (up to 100 UUIDs) that distinguish it from the single-delete sibling clients_delete. However, it doesn't explicitly name the alternative (clients_delete) or the related suppliers_bulk_delete sibling, though the bulk nature is clear from the name and description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies batch usage ('multiple clients in a single request') and the 100-UUID constraint provides some usage framing, but it gives no explicit when-to-use guidance versus clients_delete, and doesn't state when bulk delete is preferred over individual deletes. There's no exclusion guidance or mention of company context requirements beyond the schema field.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does state the key constraint (clients with invoices/documents cannot be deleted), which is valuable behavioral context. However, it doesn't disclose whether deletion is reversible, what happens to related records, permission requirements, or the response format. For a permanent destructive operation with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that state the primary function and one critical constraint. No wasted words, though it could be slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose and key safety constraint. Given the 100% schema coverage documenting both parameters, and the critical deletion constraint stated, the description is mostly sufficient. However, for a permanent destructive action with no annotations and no output schema or error documentation, omitting the response format and related-record impact leaves some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 the uuid and companyId parameters clearly. The description repeats the uuid concept implicitly (delete by UUID) and the single constraint that should trigger an error. It adds little beyond what the schema conveys, meeting the baseline of 3 but not exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Permanently delete a client by UUID' with a specific verb (delete), resource (client), and identifier type (UUID). It also differentiates the scope by noting the deletion constraint on clients with invoices/documents, distinguishing this from bulk_delete and other client operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when NOT to use this tool (when a client has invoices/documents, use bulk_delete or other approaches), but it doesn't explicitly name alternatives or provide context on when this is the appropriate choice versus clients_bulk_delete. The constraint about existing invoices/documents serves as implicit guidance that this tool is only appropriate for clients without financial history, but no explicit exclusions or alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. The description does add useful context about downstream effects ('PDFs will no longer include the company logo'). However, it doesn't disclose whether this is reversible, whether the logo file is permanently deleted, or any authorization/permissions needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a tight two-sentence structure with zero waste. Both sentences earn their place — one states the core action, the other explains the practical downstream consequence. Appropriate length for a simple single-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one required parameter, full schema coverage, and no output schema, the description is reasonably complete. The explanation of the PDF effect adds meaningful behavioral context. However, as a mutating/delete operation with no annotation coverage, some additional context around reversibility or permanence would strengthen completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter (uuid, described as 'Company UUID'), so the schema fully documents the parameter. The description adds no further semantic detail about the uuid beyond what the schema provides, matching the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool removes a logo from a company ('Remove the logo from a company'). It uses a specific verb+resource structure consistent with the tool name. It doesn't explicitly distinguish from siblings, though the company_upload_logo sibling is the clear inverse counterpart, so context differentiates it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use it (to remove a company logo) but provides no explicit exclusions or alternative guidance. The immediate effect on PDFs is noted, which helps usage context, but there's no guidance on when NOT to use it or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It does explain the behavioral outcome (logo appears on PDF documents) and the format/size constraints. However, it doesn't disclose what happens on overwrite (replacing an existing logo), auth/permission requirements, or any destructive implications—which matters since companies_delete_logo exists as a sibling. The description conveys the upload+effect but omits replacement/overwrite behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact two-sentence structure that front-loads the primary action and follows with format/size constraints and the effect. Every sentence adds information: what the tool does, what's accepted, and the result. It could arguably note overwrite behavior in the same length, but as-is it's efficient with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 parameters, 100% schema coverage, no output schema, and no annotations, the description covers the key facts reasonably: accepted formats, size limit, and effect on PDFs. However, gaps include what happens on a failed upload, whether an existing logo is overwritten or must be deleted first (given the delete_logo sibling), and any response the tool returns. The absence of annotations makes these gaps more significant.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (uuid = Company UUID, filePath = absolute path to the image file). The description adds the accepted formats and size limit for filePath, which is valuable context beyond the schema. However, it doesn't add meaning to 'uuid' beyond what the schema provides, so the added value is modest—consistent with the baseline 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool uploads a logo image for a company, with a specific verb (upload) and resource (logo for a company). It distinguishes from companies_delete_logo by being the upload counterpart, though it doesn't explicitly reference that sibling. The mention of accepted formats and the destination (PDF documents) adds useful specificity beyond just the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what file types and sizes are accepted (PNG, JPG, SVG up to 2MB), which gives some usage constraints. However, it doesn't explain when to use this tool vs alternatives, nor does it mention prerequisites like the company needing to exist or already be created. The context of where the logo appears (PDFs) helps but doesn't cover when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The description indicates it returns matching codes with descriptions, which is some behavioral disclosure, but it's largely a safe read/search operation. It doesn't disclose whether the tool is read-only explicitly, doesn't describe pagination/filtering behavior beyond the limit param, and doesn't clarify if it's a static lookup or hits an external API. For a search tool with no annotations, this is adequate but thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact — two sentences that cover purpose, usage domain, and return format. It's front-loaded with the primary action and then contextualizes the domain. No redundancy or filler. Minor deduction for not being more explicit about the return value shape or adding usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search/lookup tool with 2 well-documented parameters and no output schema, the description covers the essentials. It explains what CPV codes are, where they're used, and what the tool returns. However, it doesn't mention the sibling nc_codes_search for comparison, and doesn't clarify edge cases like exact vs. fuzzy matching or the meaning of the returned code format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (search query and limit). The description adds context that search matches by 'code number or description text', which reinforces the search parameter's semantics. However, it doesn't go beyond what the schema states for either parameter, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb+resource: 'Search CPV classification codes by code number or description.' It distinguishes itself by noting CPV codes are used in e-Transport declarations and public procurement, and explains the return format ('matching codes with their descriptions'). However, it doesn't explicitly differentiate from its sibling nc_codes_search, which appears to be an analogous tool for NC codes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context — searching CPV codes for e-Transport and procurement purposes. However, it provides no explicit when-to-use vs. when-not-to-use guidance, and doesn't mention the alternative nc_codes_search (for NC codes) that an agent might confuse this with. The context around CPV codes is helpful but no exclusions or alternative tool references are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The description discloses a meaningful behavior: the server sets status to PROCESSING and dispatches status checking, which is a state transition the user should know about. However, it doesn't disclose failure behavior, validation errors, or what happens if the upload ID extraction fails. It also doesn't mention auth requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence covers purpose and effects without redundancy. Efficient and front-loaded, though it could benefit from a second sentence on failure/error behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must explain return values and outcomes. It describes the server-side state transition but omits the response shape, polling flow, or error conditions. For a submission tool with complex ANAF response handling and status dispatch, this is a meaningful gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the structured field descriptions already document each parameter (id, statusCode, body, headers, companyId). The description doesn't add meaning beyond the schema — it mentions the upload ID extraction from the response but doesn't clarify which parameter yields it or any format requirements for statusCode/body. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Submit') with a clear resource ('the ANAF response') and explains the server-side behavior (parses, extracts upload ID, sets status to PROCESSING, dispatches status checking). It distinguishes this as the 'agent_result' submission path, though it doesn't explicitly contrast with sibling tools like declarations_submit or declarations_prepare.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool — when a local agent has received an ANAF response that must be submitted back. However, it doesn't explicitly state when NOT to use it, nor does it contrast with alternatives like declarations_submit, declarations_sync, or declarations_prepare. The 'via the local agent' phrase gives some contextual framing but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden of disclosing behavior. It discloses the async 202 behavior and outlines the actions performed (creates records, downloads, updates statuses), which is good. However, it doesn't mention authorization requirements, rate limits, failure modes, or whether the operation is destructive/reversible — significant gaps for a tool that creates records and mutates statuses.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a tight three-sentence block — the first states the purpose and scope, the second outlines the concrete steps performed, the third relays the async response. Each sentence earns its place, though the phrase 'downloads recipise' appears to be a typo for 'recipise' (likely 'receipts'), which slightly detracts.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool performs a complex multi-step mutation (create records, download, update statuses) with no annotations and no output schema, yet the description is only 3 sentences. It doesn't explain prerequisites (ANAF token/auth), what happens on partial failures, idempotency of re-running sync for the same year, or the meaning of the 202 response beyond 'async processing'. For the complexity involved, more detail is warranted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes both parameters (year with example, companyId as company UUID). The description adds 'overrides STORNO_COMPANY_ID env var' context implicitly but the schema already captures this. The description doesn't add much beyond schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (sync), resource (declarations from ANAF), and scope (for a given year). It outlines the multi-step behavior: discovers filed declarations via SPV messages, creates missing local records, downloads recipise, and updates in-flight statuses. While it clearly distinguishes from the generic declarations_* tools, it doesn't explicitly name sibling tools like anaf_sync_trigger to differentiate the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (syncing declarations from ANAF for a year) and notes the async return (202), but doesn't explicitly state when to use this vs alternatives like anaf_sync_trigger or declarations_refresh_statuses. Given sibling tools with overlapping ANAF sync and declaration status concepts exist, explicit exclusions or alternative guidance would be valuable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action (send email with PDF attached) but doesn't disclose important behaviors: whether this consumes/sends external email (side-effecting), whether a template is required, what happens if the delivery note is already sent or with a specific status, or how the PDF is generated. For a side-effecting send operation with zero annotations, this is a meaningful gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that efficiently covers the core action and key customization options (subject, body, CC, BCC). No wasted words. It's slightly on the thin side for an 8-parameter tool, but it communicates the essential functionality without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, no annotations, no output schema, and no behavioral detail beyond 'sends email', the description is somewhat thin for a side-effecting operation. The core purpose is clear and the schema covers parameter meaning, but the description doesn't address prerequisites (delivery note state), template dependency details, or failure/error behaviors. Given the tool complexity and lack of annotations, more context would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 8 parameters have descriptions in the schema. The tool description adds marginal value by noting body and subject are auto-generated if omitted (affecting how agents decide to pass them). The templateId references an email template with category delivery_note, which is useful but not elaborated. Baseline 3 is appropriate since the schema already documents parameters well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Send), resource (delivery note), and medium (via email) with the PDF attached. It also distinguishes the core function from siblings like delivery_notes_email_defaults and delivery_notes_email_history by framing this as the actual sending action. The custom subject/body/CC/BCC support is explicitly mentioned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (send a delivery note via email) but does not explicitly state when not to use it or reference alternatives like delivery_notes_email_defaults for configuring defaults or delivery_notes_email_history for viewing past sends. Some context is implied through the mention of auto-generated fields, but there's no explicit guidance on preconditions (e.g., delivery note must exist/be issued).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention pagination behavior (though page/limit params imply it), ordering, whether results include only non-deleted items, or that the selected company scoping might be overridden by companyId. For a read/list tool the safety profile is implied ('list' being non-destructive), but no behavioral detail about filtering semantics or response characteristics is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, clean and efficient. The first sentence front-loads the purpose and filter options; the second adds useful domain context about what delivery notes represent. No wasted words or redundant restatement of the schema. Structured well for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 100% schema coverage and no output schema, the description covers the purpose and filter dimensions adequately. Missing elements include pagination/defaults mention (though schema covers this), ordering behavior, and whether the company scoping can be overridden. The tool is relatively simple (list with filters), so this is adequate but not complete—no mention of return format, sorting, or how pagination interacts with filters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 8 parameters are already documented in the schema. The description adds context that delivery notes are scoped to a company and that status/date range/client/search are the filter dimensions, which maps roughly to params. However, it adds no meaning beyond the schema for individual parameters like status enum semantics, date format, or clientId meaning beyond 'Filter by client UUID'. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists delivery notes for the selected company with optional filters and explains what delivery notes document (physical delivery of goods or completion of services). It distinguishes itself from delivery_notes_get and delivery_notes_create siblings, though it doesn't explicitly contrast with them. The verb 'list' plus resource 'delivery notes' plus filter capabilities is specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies that this is a listing tool scoped to the selected company and enumerates the filter dimensions (status, date range, client, search term). It provides context for when to use it (listing delivery notes), though it doesn't explicitly state when NOT to use it vs. the alternative delivery_notes_get (single-record retrieval) or when to prefer it. With 8 sibling delivery_notes_* tools, more explicit exclusion would strengthen this, but the listing scope is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the storno is created as a draft and can be issued separately — useful behavioral context. However, it doesn't mention that negated quantities are used (though this is implied in the first sentence), doesn't state whether the original delivery note is affected/destroyed/cancelled, and doesn't describe what happens if the source delivery note is not in an issuable state. For a mutation tool with no annotations, this is a moderate disclosure level.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and includes the key behavioral note about draft status. There's minimal waste. It could potentially be more concise, but the current length is reasonable and every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description must do more work. It covers the core purpose and draft status, but for a mutation tool that creates a new document based on an existing one, it doesn't disclose whether the original delivery note remains unchanged, what preconditions apply (e.g., must be issued, not already storno'd), or what the response/return format looks like. This is adequate but leaves meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning both parameters (uuid and companyId) are already described in the schema. The description refers to 'an existing issued delivery note' which maps to the uuid parameter. However, the description doesn't add detail beyond what the schema provides — it doesn't clarify the companyId override behavior beyond the schema's own text, so it rests at the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: creates a storno delivery note with negated quantities from an existing issued delivery note. It uses specific verbs ('Create', 'storno') and identifies the resource (delivery note). It distinguishes somewhat from siblings by clarifying it creates a draft rather than issuing immediately, though it doesn't explicitly differentiate from delivery_notes_cancel or delivery_notes_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the 'when' context — that this is for storno/return operations on an issued delivery note — which implies when it should be used relative to alternatives like delivery_notes_cancel or delivery_notes_create. However, it doesn't explicitly name alternative tools or state when NOT to use this tool, leaving the differentiation implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses two behaviors beyond the schema: it removes provider settings AND disables submissions for that provider, AND notes existing submissions are unaffected. This is useful non-obvious side-effect disclosure. However, it doesn't mention irreversibility, whether this affects other companies sharing the provider, or any auth/permission requirements, so it's adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with no waste. Front-loads the purpose in sentence one, then adds behavioral context in sentences two and three. Efficient and structured appropriately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple schema (2 params, both documented) and no output schema, so the description is reasonably complete for a straightforward delete operation. The side effects are disclosed. However, it could benefit from noting whether deletion is permanent, whether it cascades to related data, and explicit permission needs—gaps that matter for a destructive config operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (provider enum and companyId with default behavior). The description adds minimal parameter-level meaning beyond the schema—it doesn't elaborate on provider choices or edge cases for companyId. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb+resource: 'Delete an e-invoice provider configuration for a company.' It distinguishes the action from siblings like einvoice_config_save and einvoice_config_test by explicitly noting removal of settings and disabling submissions. It doesn't explicitly name alternative tools, but the delete semantic is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies deletion is for removing a provider setup, and states that existing submissions are not affected (a useful behavioral note). However, it doesn't provide explicit guidance on when to use this vs. einvoice_config_save (i.e., no 'use save to modify, use this to remove' contrast), and doesn't mention prerequisites like whether the provider must be currently configured or the consequence of re-adding after delete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden alone. It discloses the quirk that ANAF submissions are tracked separately and may not appear here, and lists return fields (status, external IDs, error messages, metadata). It doesn't state auth requirements, pagination behavior, or any side effects, but for a read/list tool the disclosure is reasonably adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core purpose. The provider examples and ANAF caveat are valuable, not filler. It could drop the provider enumeration to be tighter, but it adds substantive value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with 100% schema coverage, the description is reasonably complete. It names the providers, the return fields, and flags the ANAF exception. Gaps: no mention of date-range/status filtering options or ordering, and no output schema means return format details could be more explicit. But the essential context for correct invocation is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with uuid described as 'UUID of the invoice' and companyId as 'Company UUID (uses default if not specified)'. The description implicitly clarifies the uuid refers to the invoice being queried, but adds little beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('List all e-invoice submissions for a specific invoice') and explicitly scopes the resource by filtering to a single invoice. It distinguishes from siblings by enumerating the providers (ANAF, XRechnung, SDI, KSeF, Factur-X) and the data returned. It doesn't explicitly contrast with a sibling like einvoice_submit or anaf_sync_log, but it's clearly a read/history tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to view submission history for a specific invoice, which provides clear context. However, it doesn't explicitly state when to use this vs alternatives like anaf_sync_log or efactura_messages_list, nor when NOT to use it. The ANAF caveat is helpful but is a limitation note rather than a usage directive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the read-only nature implicitly (returns available sources/types, no mutation implied) and lists concrete example values, which is helpful. However, it doesn't disclose details like pagination, whether results are company-specific vs global, or response shape/structure, and the return format is unspecified since there's no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence that conveys purpose plus concrete example values, with no wasted words. It front-loads the core purpose then provides enumeration details. Could be slightly tighter but is appropriately sized for a simple lookup tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a low-complexity tool (1 optional param, no output schema, no nested objects), so the requirements are modest. The description covers the core purpose and example return values adequately. However, without an output schema, the agent cannot know the exact response structure, and the description doesn't reveal whether the returned data is company-specific (tied to companyId) or global, which is a meaningful gap given the one parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single optional companyId parameter, which has a clear description ('Company UUID override (uses active company if not set)'). The description mentions the tool returns import sources/types but doesn't add meaning about how companyId affects the result set, though with only one well-documented parameter this is acceptable. No additional parameter meaning is needed beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb+resource (get import sources) and explicitly enumerates the specific import sources (SmartBill, Saga, Oblio, FGO, Facturis) and import types (clients, products, invoices_issued, etc.), which makes the purpose very concrete. It distinguishes from the broader import_* sibling tools (import_preview, import_execute, etc.) by being the enumeration/introspection endpoint, though it doesn't explicitly name them as alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a discovery/lookup tool for enumerating what import sources and types are available, which distinguishes it from the actual import execution tools (import_execute, import_upload, import_preview). However, it doesn't explicitly state when to use it vs. those alternatives, nor give guidance on what precedes it in a workflow (e.g., 'call this before import_upload to know supported types').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states it returns a count and per-item errors, which is useful. However, it does not disclose whether cancellation is reversible (there's an invoices_restore sibling), requires auth/role permissions, has side effects on related documents (payments, proforma conversions), or interacts with e-invoicing/efactura submission state. For a mutation tool with zero annotations, this is insufficient behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, efficient sentence that packs in the operation, the optional-reason modifier, and the return value summary. No wasted words. Could arguably mention the 1-100 limit but the schema already handles that. Well structured for parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action and return shape adequately for a batch operation. However, there's no output schema and no annotations. Gaps include: side effects on related records, whether partial failures roll back or commit, and the meaning of error elements in the response. For a batch mutation with sibling restore/storno tools, more context around behavior would help But given the relatively simple 3-param interface, this is minimally acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are fully documented in the schema (ids 1-100, reason, companyId). The description adds minimal value beyond the schema, naming the optional reason parameter but not explaining companyId override semantics beyond what the schema already states. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool cancels multiple invoices in batch, with an optional reason, and distinguishes it from single-invoice operations like invoices_cancel. 'Cancel multiple invoices in batch' is a specific verb+resource+scope formulation. It is distinct from sibling tools like invoices_bulk_storno, invoices_bulk_mark_paid, and invoices_bulk_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for batch cancellation but doesn't explicitly distinguish when to use this vs invoices_cancel (single) or invoices_bulk_storno. No when-not guidance or alternative tool mentions. The 'batch' framing provides some context, but there's no explicit guidance on edge cases like already-cancelled invoices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose the critical async behavior for large batches and the job ID return for polling. However, it doesn't disclose what happens for small batches (synchronous direct ZIP return?), any authentication requirements, or whether data is destroyed/modified. Lacks both a concrete return format for sync case and the polling endpoint name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary purpose in sentence one, behavioral note in sentence two. Every sentence adds value. No filler or redundancy. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the async behavior for large batches, the description could be more complete about what the synchronous response looks like for small batches and how the job ID ties into exports_download or other polling tools. There's no output schema, so the description should explain the return value but doesn't. For a tool with 100% schema coverage and 4 params, it's adequate but leaves the sync/async response contract ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 4 parameters are documented in the schema (direction required, dateFrom/dateTo filters, companyId override). The description adds no parameter-level semantics beyond the schema. Baseline 3 is appropriate since the schema handles parameter documentation fully, though the description could have clarified how dateFrom/dateTo combine with direction.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: 'Export e-Factura XML files as a ZIP archive.' It uses a specific verb (export) and resource (e-Factura XML files) with output format (ZIP). It doesn't explicitly distinguish from siblings like invoices_export_zip, invoices_export_saga_xml, or invoices_export_csv, but the e-Factura XML specificity is reasonably clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context signal about large batches (>100 invoices) being processed asynchronously with a job ID to poll. However, it doesn't provide explicit 'when to use this vs alternatives' guidance relative to invoices_export_zip, invoices_export_csv, or invoices_export_saga_xml. The async behavior is implied as 'for large batches' but no polling tool reference is named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states 'permanently inaccessible' which conveys irreversibility, which is good. However, it doesn't disclose whether auth/permissions are required, what happens to the returned response, or whether companyId contexts matter for revocation. A 'revoke' action is inherently destructive, and the description should more explicitly flag irreversible loss.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero wasted words. The effect (permanent revocation), the key input (linkId) and its source (invoices_share_links_list) are all packed efficiently upfront.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-param tool with a clear destructive action and full schema coverage, the description is reasonably complete. It clearly warns of permanence. However, given no annotations and that this is a destructive mutation, a bit more behavioral context (e.g., whether the revoke fails if the invoice is shared elsewhere, or auth expectations) would improve completeness. The sibling tool invoices_share_links_create provides the complementary action context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters are documented. The description adds the key cross-reference that linkId comes from invoices_share_links_list, reinforcing its provenance. companyId's override semantics are already in the schema. The description adds marginal context beyond the schema, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb-resource pair ('Revoke/delete a share link for an invoice') and clearly conveys a destructive, permanent effect ('permanently inaccessible'). It distinguishes somewhat from siblings like invoices_share_links_list/create through the revoke action, though the title already conveys this clearly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (calling after invoices_share_links_list to get linkId) and notes the effect is permanent, but doesn't explicitly state when NOT to use it or alternatives. It does give a helpful pointer to the related list tool for the linkId source.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It states this is a read operation (download, returns XML text), which is helpful, and explains the standards compliance (CIUS-RO, EN 16931). However, it doesn't specify behavior for invoices without an issued state (error handling, edge cases) or whether this only works for issued invoices specifically.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action and return format. The second sentence adds meaningful context about standards compliance. No wasted words, though the placement of the return format info could be more prominent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter download tool with no output schema, the description covers the core purpose and format. However, it doesn't note that only issued invoices are downloadable (the name implies this), or how this relates to the ANAF e-Factura submission workflow (e.g., is this the same file that einvoice_submit would use?). It's adequate but could clarify issuance-state requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (uuid and companyId). The description adds the companyId override behavior context by referencing 'issued invoice' and the ANAF purpose, but doesn't add meaning beyond the schema for either parameter. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Download') and resource ('UBL 2.1 XML file for an issued invoice'), and specifies the return format ('XML text content'). It distinguishes itself from schema-related tools by focusing on the XML download. However, it doesn't explicitly contrast against siblings like invoices_pdf, invoices_export_saga_xml, or invoices_export_efactura_zip, which are similarly download/export-oriented.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context ('format required for ANAF e-Factura submission') which gives some sense of when to use it, but it doesn't explicitly state when NOT to use it or name alternative tools. With siblings like invoices_export_efactura_zip and invoices_submit available, explicit differentiation would help the agent choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses that each preference controls four delivery channels and lists valid event types, which is useful. However, it doesn't state whether this is a partial update (only provided fields change) or a full replacement of preferences, and whether an omitted channel resets to disabled. For a settings-mutation tool, this merge-vs-replace behavior is an important gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact two-sentence structure that front-loads the purpose and then enumerates the event types. No wasted words, though the enumerated list could arguably be moved to the schema's enum constraints instead of the description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a settings mutation tool with no annotations and no output schema, the description is reasonably complete: it lists event types and channels. However, the partial-vs-full-update semantic ambiguity and lack of any mention of validation/error behavior leave important gaps for an agent deciding how to safely invoke this endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with all parameter fields documented, giving a baseline of 3. The description adds the list of valid eventType values and clarifies the four delivery channels, but much of this overlaps with what the schema already describes. The description adds the enumerated event types which the schema only hints at with an example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates notification preferences for specific event types and enumerates the delivery channels controlled (email, in-app, push, WhatsApp). It distinguishes itself from siblings like notification_preferences_get and notifications_list by specifying the update action, though it doesn't explicitly contrast with these sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (to update preferences for listed event types) but provides no explicit when-not-to-use guidance or mention of alternative tools like notification_preferences_get for reading current settings. The list of valid event types is helpful for usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the partial-update semantics ('Only provided fields are changed') and the authentication restriction, both valuable. However, it doesn't state whether updates take effect immediately, whether changes to redirectUris/scopes revoke existing tokens, or whether there's any validation side effects. The message is above average but lacks deeper behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, zero wasted words. The most important usage constraint (authentication restriction) is front-loaded as the second sentence. Despite more behavioral detail being possible, the current content is efficiently packed with only ~22 words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update tool with 100% schema coverage, no output schema, and no annotations, the description covers the essentials: purpose, partial-update semantics, and the critical auth restriction. However, given the auth nuance ('Cannot be called via API key'), the description could explain how authentication SHOULD be performed (OAuth2 token from a user session?). Without annotations, more behavioral disclosure would elevate completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each of the 8 parameters already described ('New name', 'New scopes', etc.). The description adds the partial-update semantics ('Only provided fields are changed'), which clarifies that all these are optional. This is valuable context that the schema alone doesn't convey, but since the schema already documents each parameter, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb and resource clearly ('Update an existing OAuth2 application'). The most valuable addition is 'Only provided fields are changed', which signals partial-update behavior. It doesn't explicitly distinguish from oauth2_clients_create/revoke/rotate_secret siblings, but the resource+verb combination is reasonably unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides one critical usage constraint: 'Cannot be called via API key or OAuth2 token'. This is an implicit authentication requirement, which is genuinely useful. However, it doesn't say when to use this vs oauth2_clients_rotate_secret, revoke, or create, nor does it indicate whether this is the right tool for enabling/disabling via isActive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It describes the requested information (usage statistics fields) which adds clarity about the response content. However, it doesn't disclose safety profile (read vs mutation) explicitly, though 'Get' strongly implies read-only. Could mention the companyId override 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, efficient, no waste. It communicates the core purpose and enriched return data in one concise sentence. Could arguably front-load the usage-statistics detail less, but it's compact and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter read tool with full schema coverage, the description is reasonably complete. It specifies what data is returned (usage statistics). No output schema exists, and the description compensates by enumerating the key returned fields. A minor gap: no mention of error cases (not found, invalid uuid) or whether companyId override affects the stats returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both uuid and companyId are documented in the schema. The description adds context about what the returned data contains (usage statistics), which is beyond the schema. The description doesn't elaborate on companyId semantics beyond the schema's 'Company UUID override', which is already reasonably clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves detailed info about a specific product by UUID, with specific verb 'Get detailed information' and resource. It lists the specific usage statistics returned. It's distinguishable from products_list (which presumably returns a collection), though it doesn't explicitly name that sibling for differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context (retrieve a product by UUID with usage stats) but no explicit guidance on when to use this versus products_list or when not to use it. No exclusions or alternative tools named. The usage context is implied by the 'specific product by UUID' phrasing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral disclosure burden. It states the status transition and readiness for conversion, which is useful, but doesn't disclose reversibility (can an accepted proforma be un-accepted?), required permissions, or whether the proforma must be in a particular prior state (e.g., sent) for acceptance to be valid. For a state-transition mutation with zero annotation coverage, this is a meaningful gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, zero waste. Each sentence earns its place: the first states the action, the second states the consequence. Could arguably mention reversibility or prerequisites, but for a simple mutation tool this is appropriately tight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-param mutation tool with a fully documented schema and no output schema, the description covers the core purpose and the downstream consequence. However, without annotations, it omits important behavioral context like whether acceptance is reversible, what happens if the proforma is already in a cancelled/rejected state, and whether any validation occurs. This creates gaps a careful agent would want clarified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema documents both parameters (uuid and companyId). The description adds no parameter-specific detail beyond what the schema already provides. Baseline 3 is appropriate since the schema does the heavy lifting and description doesn't contradict or add conflict.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb+resource ('Mark a proforma invoice as accepted') and specifies the resulting status transition ('Transitions status to accepted'). It distinguishes itself from sibling tools like proforma_invoices_reject, proforma_invoices_cancel, and proforma_invoices_convert by describing the accept workflow step. It doesn't explicitly distinguish from siblings, but the action is specific enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description sets clear context that this is the acceptance step and that after acceptance 'the proforma is ready to be converted to a final invoice', which implies the ordering relative to proforma_invoices_convert. However, it doesn't explicitly mention when NOT to use it or name alternative tools like reject/cancel, though the implicit workflow ordering provides decent guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool creates a draft-status invoice and supports currencies, discounts, and references. However, it does not disclose what happens after creation (e.g., whether it's immediately available, whether it must be sent/issued separately via proforma_invoices_send), how invoicing numbering is handled, or what the response contains. For a mutation tool with zero annotations, this is a notable gap, though the core mutating behavior is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the purpose ('Create a new proforma invoice in draft status with line items') and then lists key capabilities. It is efficient with no fluff. Could arguably enumerate more behavioral detail, but for conciseness metrics this is well-structured and appropriately brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 22 parameters (7 required) and no output schema, the description is minimal but the schema's 100% coverage compensates somewhat. However, the tool has no annotations and no output schema, and the description does not clarify default behaviors, required series configuration, or the relationship to companion operations (send, convert, accept). For a complex creation tool with many related sibling proforma operations, the description leaves the agent to infer several behavioral aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and all 22 parameters have descriptions in the schema. The description adds general context about capabilities (currencies, discounts, references) but does not detail any specific parameter semantics beyond what the schema already documents. Per the rubric, high coverage yields a baseline of 3, and the description does not significantly exceed the schema's documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a new proforma invoice in draft status with line items, and mentions added features (multiple currencies, discounts, optional references). This distinguishes it from related tools like proforma_invoices_update, proforma_invoices_convert, and delivery_notes_from_proforma among siblings. Could be slightly more explicit about being distinct from invoices_create (regular invoice), but the proforma-specific naming and draft-status mention provide good differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating proforma invoices in draft status but does not explicitly state when to use this versus invoices_create (regular invoices) or when a proforma should be converted rather than created directly. It does not mention prerequisites (e.g., that seriesId must reference a proforma-configured series, which is hinted only in the schema param description), and no exclusions are given. Minimum viable guidance with room for improvement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses what the response includes (line items, client info, calculated totals), which is helpful. However, for a read/get operation it doesn't disclose error behaviors (e.g., 404 for nonexistent UUID), auth requirements, or whether companyId overrides are needed, leaving meaningful gaps in behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single efficient sentence that front-loads the purpose and enumerates what's included. No wasted words, though it could arguably name the companyId scoping alternate behavior. Efficient but minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter get tool with no output schema and 100% parameter coverage, the description is reasonably complete for stating intent. However, with no output schema present, the description's list of returned contents (line items, client info, totals) is the primary signal about return value shape, and it's fairly coarse. For a get operation with no annotations and no output schema, this is adequately complete but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 uuid and companyId. The description adds that it returns line items, client info, and totals, but adds nothing about parameter semantics beyond the schema. Per the rubric, baseline 3 is appropriate when schema covers everything and no additional param detail is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Get complete details for a specific proforma invoice' with explicit inclusion of line items, client info, and calculated totals. Distinguishes adequately from siblings like proforma_invoices_list (which by naming convention lists multiple) though it doesn't explicitly contrast, and from proforma_invoices_create/update/delete/accept/reject/cancel which are clearly different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies singular fetch usage through the word 'specific', and the tool name pattern 'get' suggests retrieval, but there is no explicit when-to-use guidance or mention of alternatives. It doesn't state when to prefer this over proforma_invoices_list or when not to use it. The context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose the status transition (draft to sent) and the read-only consequence, which is valuable. However, it doesn't mention prerequisites (e.g., must be in draft status, what happens if already sent), required permissions, or error behavior if the invoice is not in draft state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences and reasonably efficient. The first sentence states the purpose, the second specifies the status transition, and the third discloses the read-only consequence. It's front-loaded with the action verb and resource. Minor redundancy between sentence 1 and sentence 2 could be trimmed but overall it's compact and purposeful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple state-transition tool with 2 well-documented params and no output schema, this description is mostly adequate. It explains the effect (read-only after send) and the status change. Missing elements include failure conditions (what if not in draft state?) and whether any notification/email is actually sent to the client. Given the simplicity and no nested objects, the gaps are modest but present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are documented in the schema. The description doesn't add semantics beyond the schema for either parameter — uuid and companyId are already clearly described. The description's behavioral note about the transition adds context but not parameter-level detail, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Mark a proforma invoice as sent to the client') and the specific resource (proforma invoice). It distinguishes from siblings like proforma_invoices_accept, reject, cancel, and convert by specifying the draft-to-sent status transition. However, it doesn't explicitly name sibling alternatives, which keeps it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (for marking sent, transitioning from draft to sent) but doesn't explicitly say when to use this vs alternatives like proforma_invoices_accept or proforma_invoices_convert. No exclusion criteria are provided, though the read-only consequence is a useful cue about the irrevocable nature. The when/alternatives guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that cancellation preserves the historical record (unlike deletion), which is valuable behavioral context. However, it does not state whether cancellation is reversible (e.g., via receipts_restore), whether the receipt becomes un-editable, or what downstream impacts occur. Given zero annotation coverage, more disclosure would be warranted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, concise and efficient. It front-loads the core action and adds the key differentiator (historical preservation). No fluff or repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a cancellation/mutation tool with no annotations and no output schema, the description covers the key behavior and status constraints but leaves gaps: reversibility, effect on linked records (payments, invoices), and whether any authorization is needed. It also doesn't clarify the notes-vs-reason distinction. Adequate but not rich enough for a state-changing financial operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 4 params are documented in the schema. The description adds marginal value by mentioning the optional cancellation reason, which maps to cancellationReason/cancellationNotes, and it notes the required uuid implicitly. It doesn't clarify the semantic difference between cancellationNotes and cancellationReason, which are ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb+resource ('Cancel a receipt') and specifies the valid source statuses ('draft or issued'). It distinguishes cancellation from deletion by noting it preserves the historical record, which helps differentiate from sibling tools like receipts_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it ('cancel from draft or issued status') and implicitly contrasts with deletion, but does not explicitly name alternatives or state when NOT to use it. It does not mention that refunds would be handled by receipts_refund, which is a relevant sibling distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses it sends a PDF and supports custom subject, body, CC, BCC. However, it doesn't disclose side effects like whether a history record is created, whether it changes receipt status, or email delivery failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the purpose and then lists supported customizations. It's efficient with no wasted words. Could arguably be more informative given its brevity, but it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an email-sending tool with 8 parameters and no output schema, the description covers the core action and customizations but omits context around how receipts are tracked after sending (history), whether sending marks the receipt as issued/emailed, or what errors occur. With siblings like receipts_email_defaults and receipts_email_history present, more context about the sending lifecycle would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all 8 parameters are documented in the schema. The description adds marginal context by explaining that subject/body auto-generate if omitted (which the schema also mentions) and that companyId overrides the configured default. But it doesn't explain the uuid parameter relationship beyond schema coverage, and text explaining the purpose of templateId (category: receipt) is only in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Send a receipt (bon fiscal) to a customer via email with the PDF attached.' It uses a specific verb+resource (send receipt via email) and mentions the PDF attachment detail. It doesn't strongly distinguish from siblings like invoices_email or receipts_email_defaults, but the core purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for emailing receipts but provides no explicit when-to-use vs alternatives guidance. There's no mention that receipts_email_defaults or receipts_email_history exist or when this should be preferred over those. It doesn't state exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'Replaces all line items with the provided array,' which is a key destructive/replacement behavior worth knowing. However, it doesn't disclose whether status transitions, validation, or side effects (e.g., recalculating totals) occur, nor what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The key constraints (status limitations and line-item replacement) are front-loaded. Could arguably mention the note that line-item replacement also affects line-item UUIDs, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 24-parameter mutation tool with no annotations and no output schema, the description is reasonable but light. It captures the two essential behaviors (status gate and line replacement) but does not touch on whether existing line-item UUIDs must match, potential validation errors, or return semantics. Given the tool's complexity, more guidance would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well documented by the schema itself. The description adds the critical semantics that the 'lines' array replaces all existing line items and that draft/issued status is required — valuable context the schema alone doesn't convey. A baseline 3 is appropriate since the schema already handles most param documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool updates an existing receipt and clearly distinguishes the line-item replacement behavior. It doesn't strongly differentiate from sibling tools like receipts_create or receipts_issue, but the verb+resource action is clear and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes that receipts in draft or issued status can be updated, implying status constraints. However, it doesn't explicitly state when NOT to use this vs. tools like receipts_issue, receipts_cancel, or receipts_convert_to_invoice, nor any exclusions for already-finalized receipts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the key behavioral trait: automatic invoice generation on a schedule. However, it doesn't mention auth/permission requirements, side effects of creation, or what the response contains since there's no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose. All content is relevant. Could arguably drop the pricing-rules enumeration to the schema, but it's useful high-level context. Efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex tool (24 params, 10 required) with no output schema and no annotations. The description is adequate but minimal for this complexity. It doesn't explain relationships among the many interconnected fields (e.g., frequencyDay for monthly vs frequencyMonth for yearly, dueDateDays vs dueDateFixedDay dependencies) which would help the agent satisfy the required-parameter constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents all 24 parameters with descriptions. The description adds value by summarizing the pricing rule options (fixed, updated_product, bnr_rate, bnr_rate_markup) which mirrors but slightly condenses schema text. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states it creates a recurring invoice template with automatic invoice generation based on frequency/schedule. Clear verb+resource. It distinguishes from sibling create tools like invoices_create (one-off) and proforma_invoices_create, though it doesn't explicitly address the recurring_* sibling family.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what it does but doesn't explicitly state when to use this vs the one-off invoices_create or the update/toggle siblings. The automatic-generation behavior is implied as the use case but no explicit exclusions or alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It does disclose a critical behavior: the requirement for company context (X-Company header/companyId/env var). However, it doesn't state whether this is read-only, what permissions are needed, whether the report has limitations (e.g., currency, tax regime assumptions), or whether it blocks on external data (e.g., ANAF sync). This is a moderate disclosure but incomplete for a report that may feed into tax compliance decisions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence that front-loads the purpose and then enumerates the output contents and the company-context requirement. Efficient with no wasted words, though slightly packed in one long sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool returns a structured report with per-invoice details and multiple summarized figures, and there's no output schema. The description does enumerate what the report returns, which compensates somewhat. However, it doesn't clarify how the per-invoice details are structured, whether results are paginated, or what date semantics apply (calendar month vs. accounting period). For a compliance-relevant reporting tool, more behavioral detail would be valuable, but the description covers the essentials for a simple month-scoped query.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all three parameters (year, month, companyId). The description adds context by noting companyId overrides the STORNO_COMPANY_ID env var, which maps to the schema's own description. It doesn't add extra meaning about the year/month format or edge cases beyond what schema provides. Baseline 3 is appropriate since schema handles the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a detailed VAT (TVA) report for a month, listing what the report contains (sales, purchases, VAT collected/deductible, net due) and per-invoice details. It's a specific verb+resource+scope, though it doesn't explicitly distinguish from the sibling reports_sales_analysis tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates it requires the X-Company header via companyId param or STORNO_COMPANY_ID env var, which is useful context. However, it doesn't explain when to use this versus other reporting/analysis tools (e.g., reports_sales_analysis, declarations_*, cash_register). The monthly scope is implied but the selection criteria among sibling reporting tools are not addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description declares a significant behavior: it writes and reads a test file to verify credentials and permissions, which implies potential side effects on the storage bucket. It also notes it falls back to existing config credentials. However, there are no annotations, and it doesn't disclose what happens on failure (e.g., whether it creates/destroys artifacts, cost implications of writes).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, efficient and to the point. Every sentence carries meaningful information: the first explains the tool's function, the second clarifies the credential fallback behavior. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a test tool with 8 optional parameters, no output schema, and no annotations, the description explains the core mechanism (write+read test file) and the fallback credential behavior. However, it doesn't specify what success/failure looks like in the response, whether the test file is cleaned up afterward, or how the many optional parameters interact when some but not all are provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 8 parameters are already documented (bucket, region, endpoint, provider, accountId, accessKeyId, forcePathStyle, secretAccessKey). The description adds the useful context that credentials may come from existing config if not provided, which is meaningful beyond the schema. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool tests an external storage connection by writing and reading a test file to verify credentials and permissions. This is a specific verb+resource+method that distinguishes it from config_get/update tools, though it doesn't explicitly name sibling alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does (tests credentials/permissions) and that it uses existing config credentials if not provided. However, it doesn't explicitly say when to use this over storage_config_get or storage_config_update, nor does it state prerequisites (e.g., that a config must exist first).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It adds one valuable behavioral fact — 'Credentials are encrypted at rest' — which is useful reassurance. However, it doesn't disclose other important behaviors: whether this is a full replacement (requires all credentials each call) vs partial update, credential validation timing, idempotency semantics, or what happens to existing config. For a mutation tool with zero annotation coverage, this is a moderate gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences focused on provider support and security. Front-loaded with the core verb+action. The provider examples list is slightly verbose but useful for agent selection. No wasted words or redundancy with schema fields. Could be tightened but is reasonably efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter configuration mutation tool with no annotations or output schema, the description is somewhat thin. It doesn't clarify required credential combinations, whether this replaces the entire configuration, or behavioral consequences (e.g., is storage switched immediately upon activation?). It does convey the key security property and provider scope. Adequate but could meaningfully improve with update-vs-create semantics and credential requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents all 10 parameters well. The description adds some value by explaining the provider list meaning (S3-compatible) and the encryption detail, but doesn't extend parameter semantics (e.g., which params are required together, what happens if only some are provided, endpoint vs region relationships). Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb+resource ('Create or update external storage configuration') and specifies supported providers. It's distinguishable from siblings like storage_config_get, storage_config_delete, and storage_config_test, though it doesn't explicitly name these alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it supports S3-compatible providers and lists examples, giving some context for when to use it. However, it doesn't explain when to use update vs create semantics, when to choose this over storage_config_test/get/delete, or any preconditions (e.g., needing provider list first). No explicit exclusions or alternatives named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the idempotent behavior (returns existing supplier on duplicate CIF), which is genuinely valuable. However, it doesn't disclose auth requirements, rate limits, what happens on validation failure, or side effects. The dedup disclosure is a positive but partial picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both informative. The first establishes purpose and requirements; the second adds the critical dedup behavior. No wasted words. Could be slightly more structured but is efficient and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with 16 parameters and no output schema, the description covers the core required fields and dedup behavior. However, given the high parameter count and no output schema, it could clarify what the response contains (created vs existing supplier), whether this creates a companyId, or note that most fields are optional. The dedup note partially compensates but the overall picture has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 16 parameters are documented in the schema. The description adds the dedup-by-CIF behavioral note and mentions required fields (name, county, city, address, registration number), which maps to the 5 required schema fields. However, it doesn't add semantic depth beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new supplier manually' with a specific verb and resource. It lists the required fields and distinguishes from siblings like suppliers_update and suppliers_bulk_delete. However, it doesn't explicitly differentiate from other create tools, but the supplier-specific scope is clear enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the required fields and the deduplication behavior ('returns existing supplier instead'). It implies usage for manual supplier creation but provides no explicit when-not-to-use guidance or alternatives. The dedup behavior is useful but the description doesn't specify prerequisites or relationships with other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the disclosure burden. It correctly implies this is a read-only listing operation and adds the behavioral note about automatic creation via ANAF e-Factura sync (useful context about data provenance). However, it doesn't disclose return format, pagination behavior beyond schema-defined params, or any rate limits. The description adds value but leaves gaps in behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences of meaningful content: the primary purpose, the data provenance detail, and the search capability. Each sentence earns its place with distinct information. Front-loaded with the core action in the first sentence. Slightly more verbose than an ideal two-sentence description, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters (all optional), no output schema, and no annotations. The description explains the core listing behavior, the search capability, and supplier provenance. For a straightforward list tool this is reasonably complete, but it lacks information about the return structure, whether the result set includes all supplier fields, and pagination semantics. Given the relatively simple nature of a list operation, this is adequate but could note what fields are returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all four parameters (page, limit, search, companyId). The description adds marginal value by explaining that search works 'by name, CUI, or email' and clarifying that companyId 'overrides configured default' — this latter point is genuinely useful context beyond the bare schema. Baseline 3 is appropriate with the small bonus from the search-field clarification.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: 'List suppliers for the selected company grouped alphabetically.' The verb 'list' plus the resource 'suppliers' plus the scope qualifier 'for the selected company' and the grouping detail make the purpose specific. It doesn't explicitly differentiate from sibling list tools like suppliers_get, but the verb+resource is clear enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes suppliers are 'automatically created from incoming invoices via ANAF e-Factura synchronization,' which gives useful context about when suppliers exist in the system. However, it doesn't explicitly state when to favor this over alternatives like suppliers_get or suppliers_create, nor does it mention when-not-to-use scenarios. The guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses two important behavioral traits: a maximum of 5 active links per user and short link expiration. However, with no annotations provided (no readOnlyHint, no destructiveHint), the description carries the full burden for disclosing side effects. It doesn't state whether this is creates state (it does), what happens when the 5-link limit is reached, or how the returned token URL should be handled in subsequent calls. The limit and expiry disclosures are valuable but partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise at three sentences, front-loading the core purpose and then providing key constraints (5-link limit, expiration). Every sentence contributes useful information. It could be slightly tighter, but there's no waste. The structure is effective for the information conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with clear description, the core function is well covered. However, given the complexity of the ANAF OAuth flow (evident from sibling tools like anaf_sync_status, anaf_tokens, anaf_status), the description doesn't explain the subsequent flow steps or how this link connects to other ANAF tools. Lifecycle context—what to do after obtaining the link, how to check completion—is missing. No output schema means the description should more thoroughly describe the return value structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters, and the context signal indicates 100% schema description coverage. With no parameters to document, the baseline is 4 per the rubric. The description adequately explains what the tool returns (a unique browser-openable URL) without needing to elaborate on parameter details that don't exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a device-based authentication token link for the ANAF OAuth flow, with a specific verb (create) and resource (token link). It provides good purpose clarity with details about the returned URL and its use in browser authentication. It doesn't explicitly distinguish from adjacent ANAF sibling tools like anaf_sync_trigger or anaf_delete_token, though the distinct 'create token link' function is evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the first step in completing ANAF OAuth flow, suggesting it should be used before authentication steps. However, it doesn't explicitly say WHEN to use this vs alternatives, nor does it mention subsequent steps like polling the token status (anaf_status/anaf_tokens). The context is implied rather than explicit, and there's no exclusionary guidance about when NOT to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. Given the read-only nature (a status/get operation with zero parameters), the description adequately conveys what data is returned: whether sync is enabled, last sync timestamp, token validity, and sync frequency. However, it doesn't disclose potential side effects (if any), authentication requirements, or what 'token validity' means precisely. For a status-check tool, this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that front-loads the purpose and enumerates the specific pieces of information returned. Zero wasted words. The sentence is focused and complete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter status/get tool, the description is complete enough. It enumerates all returned fields (sync enabled state, last sync timestamp, token validity, sync frequency interval). There's no output schema, so the description handles that burden adequately. It could arguably mention the relationship to anaf_sync_trigger (that triggering creates vs. reading status), but this is a minor gap for a status tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100% (vacuously, since there are no params to describe). The description clearly states what information the caller will receive without needing input parameters. With 0 params, baseline is 4 per the rubric, and the description doesn't detract from that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this tool retrieves the e-Factura synchronization status and configuration, specifically naming the returned data: sync enabled state, last successful sync timestamp, token validity, and sync frequency. It uses a specific verb ('Get') and resource ('current e-Factura synchronization status and configuration'). It doesn't explicitly distinguish from the sibling tools like anaf_sync_trigger (which triggers sync) or anaf_status, but the focus on configuration status is reasonably distinctive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus the many related sibling tools (anaf_sync_trigger, anaf_sync_log, anaf_status, anaf_tokens, efactura_messages_list). It does not state that this is a read-only status check, nor does it mention when a user would prefer it over anaf_sync_trigger or anaf_sync_log. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that this triggers an async operation and validates token availability and subscription plan rate limits before dispatching. This adds useful behavioral context (async nature, pre-validations). However, there are no annotations provided, so the description carries the full transparency burden. It doesn't disclose what happens on failure, whether partial failures occur (some companies have tokens, others don't), or how the agent would interpret the async dispatch result.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-structured sentence that covers the action, scope, pre-conditions (valid tokens, rate limits), and outcome (async job dispatch). No wasted words. Could potentially be more explicit but is appropriately sized for a zero-parameter operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema trigger tool, the description covers the what, scope, and async nature adequately. However, it doesn't mention what the response/return looks like (since there's no output schema), nor does it address side effects (e.g., does this trigger cost API credits, does it affect rate limits that could block other sync operations?). The async dispatch is mentioned but the agent isn't told how to check on completion (e.g., via anaf_sync_status).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters and 100% schema coverage, so there are no parameter semantics to document. Per the guidelines, 0 params earns a baseline of 4. The description appropriately focuses on behavior rather than params since there's nothing to explain about inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it manually triggers e-Factura synchronization for all companies with valid ANAF tokens, and dispatches an async job to fetch new invoices from ANAF SPV. It uses a specific verb (trigger) and resource (e-Factura synchronization). It's distinguishable from siblings like anaf_sync_status (which checks status) and anaf_sync_log (which reads logs), though it doesn't explicitly name those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a manual trigger operation (as opposed to automatic sync), which gives the agent context on when to use it. However, it doesn't explicitly state when NOT to use it, nor does it differentiate from related tools like anaf_sync_status or clients_sync_invoices which also deal with ANAF/sync functionality. Related sibling tools like anaf_sync_status could be confused with this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral disclosure burden. It correctly indicates the mutating nature of the operation and flags the conditional requirement that currentPassword must accompany password changes. However, it doesn't disclose consequences like whether all fields are updated atomically, whether omitted fields are left unchanged or reset, or whether the quiet-hours default (true per schema) applies when the field is not provided when updating other fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and follows with the enumerable fields in parentheses. It's compact with no wasted words. It could be slightly more structured (perhaps splitting the password caveat into its own sentence), but overall it earns its space without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter mutation tool with 100% schema coverage and no output schema, the description covers the primary intent and the critical password coupling. However, it doesn't explain partial-update semantics (e.g., whether passing one field leaves others untouched), which matters for a multi-field update tool, nor does it clarify the exact meaning of 'preferences' beyond what the schema offers. Given the tool's complexity, a bit more context on update semantics would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 all 8 parameters well. The description adds meaningful value beyond the schema by summarizing which fields are updatable and explicitly highlighting the password/currentPassword coupling. It also adds the quiet-hours timing clarification (22:00-08:00) that is in the schema as well. The description doesn't duplicate every parameter but adds the aggregate purpose, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Update the authenticated user's profile') with a specific resource (the authenticated user's profile) and enumerates the updatable fields (name, phone, timezone, quiet-hours preference, preferences, or password). It doesn't explicitly differentiate from sibling auth tools like auth_me or auth_update_password, but the verb+resource combination distinguishes it well from the general tool landscape.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for updating the current user's own profile, distinct from admin/user management tools. It notes a password-specific requirement (requires currentPassword when changing password), which is a useful conditional guideline. However, it doesn't explicitly state when NOT to use this tool (e.g., for other users' profiles, or when to prefer auth_forgot_password/auth_reset_password for password changes), leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It clearly states this is a read operation ('Get', 'Returns') for verification purposes, which conveys non-destructive intent. However, it doesn't disclose pagination behavior, potential size limits, or whether companyId overrides affect row visibility. Adequate but thin on behavioral detail for a read tool with no annotation safety net.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, efficient, no filler. Front-loaded with the core action and return structure, then a use-case hint. The mention of '10 numeric columns' with the parenthetical breakdown is slightly verbose but informative and earns its place by describing the return shape.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple (2 params, no output schema), so the description covers the essentials well. However, without an output schema, the description is the sole source for return structure—it names columns but not types, ordering, or edge cases (empty trial balance, error behavior). For a verification-oriented read tool, slightly more detail on what 'parsed' means and possible failure modes would round it out.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters ('Trial balance UUID' and 'Company UUID overrides STORNO_COMPANY_ID env var'). The description adds the 'parsed rows' and '10 numeric columns' context which clarifies what the tool returns relative to the id parameter. Description meaningfully frames what the id selects, and companyId's override behavior is already richly documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('parsed account rows for a trial balance'), and details the return structure (account codes, names, 10 numeric columns). It doesn't explicitly differentiate from sibling tools like balance_list or balance_reprocess, but it's more specific than balance_list. Minor gap in not naming alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes it's 'Useful for verifying PDF parsing results,' which gives a use case, but doesn't explicitly state when NOT to use it or how it differs from balance_list, balance_reprocess, or balance_delete siblings. The verification use case implies reading, but no exclusions or alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations were provided, so the description carries full burden for behavioral disclosure. It mentions key return data (IBAN, bank name, currency, default account per currency) which is helpful. However, it doesn't disclose read-only behavior explicitly, potential pagination/limits, or whether it can return empty results. The companyId override behavior is mentioned in the schema though, not fully explained in description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at two sentences, front-loaded with the core purpose. The first sentence states the action and scope, the second adds practical context about invoice usage and return data. No wasted words, though it could arguably merge the return-value hint more efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description is reasonably complete. It covers the purpose, scope, key return fields, and downstream usage context (payment instructions on invoices). The lack of output schema shifts some burden to the description, which it partially addresses by listing return fields. It lacks explicit read-only safety disclosure, but that's a minor gap for a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — the single optional companyId parameter is documented in the schema as 'Company UUID override (uses active company if not set).' The description mentions 'active company' which aligns with the schema. The description doesn't add much beyond what the schema already explains, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear purpose: 'List all bank accounts configured for the active company.' It specifies the resource (bank accounts) and the verb (list), and distinguishes from siblings like bank_accounts_create, bank_accounts_update, and bank_accounts_delete. It doesn't explicitly differentiate from any other 'list' sibling but the resource scoping is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you need to retrieve configured bank accounts) and notes that 'bank accounts appear on invoices as payment instructions,' providing some functional context. However, it doesn't explicitly state when NOT to use it or name alternatives (e.g., use bank_accounts_create to add, bank_accounts_update to modify).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It conveys that this operation modifies ('link or unlink') a transaction match, which is some transparency about mutation. However, it doesn't disclose side effects such as whether unlinking cascades to other records, whether existing matches are replaced, or what happens on partial updates with conflicting params (e.g., both invoiceId and proformaInvoiceId).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact single sentence that front-loads the purpose and gives the core behavior (link/unlink for reconciliation). It's efficient with no wasted words, though it could add a usage note without much cost.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters, no annotations, and no output schema, this mutation tool has moderate complexity. The description explains the general purpose and the companyId fallback, but leaves gaps: how amount override interacts with matching, whether documentType is required when linking, what the response format is, and what mutually-exclusive parameter combinations are valid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each of the 7 parameters is documented in the schema. The description adds the 'link or unlink' semantic for the match operation and clarifies the companyId fallback behavior ('uses active company if not set'), which goes beyond the bare schema. It also ties documentType to the invoice/proforma choice. Schema and description together cover the parameters well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Update') and resource ('borderou transaction match'), and explains the linking/unlinking behavior against invoices or proforma invoices. It distinguishes from siblings like borderou_transactions_save and borderou_transaction_get reasonably well through its explicit 'match' focus, though it doesn't name sibling alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (linking transactions to documents for reconciliation) but provides no explicit when-to-use vs alternatives guidance. It doesn't mention how this differs from borderou_transactions_save or borderou_transactions_rematch, which appear to be related sibling tools for the same domain.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral disclosure burden. It indicates this is a read operation ('Get') and lists return content, but doesn't disclose whether the UUID represents the current logged-in company or another accessible company, error cases (missing/expired company), or whether ANAF token validity is fetched live or from cached state. The read-only nature is only inferred, not stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that front-loads the primary purpose and enumerates return contents. Zero wasted words, no repetition of the schema's own parameter documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple interface (1 param, fully documented schema, read-only by nature) and an output of moderate richness. The description adequately covers the core return categories. However, given no annotations and no output schema, the description could add more value by noting behavioral details like live vs. cached data or permission requirements, leaving it at a modest completeness level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with a single parameter 'uuid' described as 'Company UUID'. The description adds context on what the returned data contains but does not clarify the UUID format or provenance (e.g., which company namespace the UUID belongs to). With full schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get'), the resource ('detailed information for a specific company'), and the identifier type ('by UUID'). It enumerates what's returned (configuration settings, bank info, sync settings, ANAF token validity status), distinguishing it from companies_list, companies_update, and companies_delete siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when retrieving single-company details by UUID, contrasting with companies_list for lists. However, it doesn't explicitly state when to prefer this over related get tools or note any exclusions or prerequisites, such as requiring admin/membership context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden of behavioral disclosure. It does disclose that core ANAF fields are immutable (a meaningful behavioral constraint: attempting to change them will fail or be ignored). However, it doesn't disclose whether this is a full replacement update (PUT semantics) or partial patch (PATCH semantics), what happens to unspecified fields, or any authorization requirements. The 'update' verb implies mutation but no side-effect details are given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient paragraph that front-loads the purpose and immediately follows with the critical constraint about immutable ANAF data. It's compact with no filler or redundancy. Could arguably be slightly more structured, but the two-sentence form is clean and delivers high-value information early.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a settings-update tool with 13 well-documented parameters, high schema coverage, and no output schema, the description covers the most critical context (which fields are editable vs synced). The main gap is not describing update semantics (full vs partial) or listing which specific fields are editable beyond the broad categories. But given the schema's strong parameter documentation and the absence of nested objects/output requirements, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents all 13 parameters. The description adds marginal value by grouping editable fields into categories ('contact info, bank details, sync settings') and clarifying that uuid is the required identifier. However, it doesn't add semantic detail beyond the schema's existing per-parameter descriptions, and with high coverage the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates configuration settings for a company, using a specific verb ('update') and resource ('company configuration settings'). It distinguishes from siblings by specifying scope: it updates settings but cannot modify core ANAF-synced data. This differentiates it somewhat from companies_create and companies_delete, though it shares the 'update' verb with many other *_update tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful context about what CANNOT be modified (core ANAF data), which serves as a partial exclusion criterion. However, it doesn't explicitly state when this tool should be used versus alternatives like companies_toggle_sync or companies_set_active. The editable-fields guidance is helpful but there's no explicit 'use this when' statement or mention of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states this is a read operation ('Get... Returns...'), which implies non-destructive behavior, and lists the return contents. However, it doesn't disclose response size limits, whether an 'id' not found returns an error vs. empty, authentication requirements, or what 'metadata' and 'error messages' specifically contain. For a getter with zero annotation coverage, the description is helpful but leaves meaningful gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, second half enumerates the return payload ('populated data, status, metadata, and error messages'). Zero wasted words, immediately scoped. Front-loaded with the verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter getter with 100% schema coverage and no output schema, the description is reasonably complete. It names the payload components. It doesn't explicitly explain the operational semantics (read-only, safe) but a getter's behavior is largely self-evident. Given the complexity level, this is adequate; a slightly richer statement on companyId's env-var override behavior would elevate it further.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are documented. The description adds value by naming the return payload composition. The description also indirectly clarifies the 'id' is a declaration UUID (matching the schema). 'companyId' is documented in the schema as overriding an env var. The description text doesn't add param-specific detail beyond what's in the schema, but with 100% coverage the baseline of 3 applies and the return-content context bumps it up.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb+resource ('Get a single tax declaration by UUID') and lists what it returns ('populated data, status, metadata, and error messages'). It distinguishes itself from declarations_list (single fetch vs. listing) and from subsequent mutation tools. Slight deduction: it doesn't explicitly contrast with the sibling declarations_get in the broader set, but the single-vs-list distinction is clear from the name and wording.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for retrieving a single declaration by UUID, which contextually separates it from declarations_list. However, there's no explicit 'use this when you have a declaration UUID' guidance, nor 'use declarations_list to find UUIDs first'. No alternative tools are named. Adequate context for a straightforward getter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that validation is a state-transitioning operation (to 'validated' status) and that it generates and checks XML, which is meaningful behavioral context. However, it doesn't state side effects beyond the status transition, failure behavior, or whether this is a mutating/write operation requiring caution. For a state-changing tool with zero annotations, more explicit disclosure would strengthen it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste. The first sentence states the primary purpose and mechanism; the second states the success outcome. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool performs a meaningful workflow step (validating a draft declaration that transitions status), yet there's no output schema and no annotations. The description mentions the status transition and XML generation, which helps, but it doesn't address what the response contains (errors? XML content?), failure conditions, or the relationship to the broader declaration workflow (prepare vs validate vs submit). Given the tool's complexity within a larger pipeline, slightly more context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both 'id' (Declaration UUID to validate) and 'companyId' (Company UUID overriding env var). The description adds the behavior tied to 'id' (validating the draft) but the companyId override nuance is only in the schema. Baseline 3 is appropriate since the schema handles the heavy lifting and the description adds minimal parameter-specific value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Validate a draft declaration'), the mechanism ('generating and checking the XML output'), and the outcome ('Transitions the declaration to validated status if successful'). This distinguishes it from siblings like declarations_prepare, declarations_submit, and declarations_recalculate, though it doesn't name them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it applies to draft declarations (via the word 'draft') and notes the success outcome, but it doesn't explicitly state when this should NOT be used, which siblings to choose instead, or any prerequisites (e.g., that the declaration must be in draft state first). Adequate but lacks explicit exclusions or alternative guidance despite a clear sibling set including declarations_prepare and declarations_submit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It correctly implies this is a read-only listing operation ('List all document series'), which sets expectations of a safe, non-mutating call. However, it doesn't describe return structure, pagination, ordering, or whether the type filter is mutually exclusive or combinable with company filtering. The description is accurate but not deeply transparent about behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus an illustrative parenthetical. It's efficient and front-loaded with the core purpose ('List all document series for the active company'), then adds contextual color about what series represent. The extra sentence about numbering prefixes and tracked numbers earns its place by helping the agent understand the domain. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but this is a list endpoint with 0 required parameters and simple optional filtering, so complexity is low. The description adequately covers what the tool does, the filter dimension, company scoping, and domain context. An output schema would help clarify return structure, but for a straightforward list tool this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters well (type enum with explanation, companyId with UUID override note). The description adds some value by explaining the type values map to document types (invoice='FAC', proforma='PRO', etc.), which goes slightly beyond the schema. The companyId override is mentioned in both schema and description. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists document series for the active company with optional type filtering. It adds contextual detail explaining what document series are (numbering prefixes for invoices, proformas, credit notes, delivery notes) and what data each series tracks (current/next available number). It distinguishes itself from sibling tools like document_series_create/update/delete through the list verb, though it doesn't explicitly contrast with a 'get' variant since none exists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly explains when to use it (listing series, optionally filtered by type) and mentions the companyId override for selecting a company. However, it doesn't provide explicit guidance on when NOT to use it or contrast with alternatives like document_series_create/update/set_default/delete. The context is implied rather than spelled out regarding interplay with series management tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral disclosure burden. 'Get details' implies a read operation, which is accurate for a GET endpoint. However, it doesn't disclose what error behavior occurs for invalid/nonexistent UUIDs, whether any permissions are required, or what specific detail fields are returned. Without annotations, this is a minimal but not rich disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is perfectly concise, front-loaded with the verb 'Get details', and contains zero wasted words. It fully covers the tool's purpose in minimal space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter GET tool with a clear sibling (oauth2_clients_list), the description is mostly adequate. However, with no annotations and no output schema, there's no mention of what details are returned (scopes, redirect URIs, client secret, status, etc.) or whether the result includes sensitive fields. For such a lightweight tool, this is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the single 'uuid' parameter described as 'OAuth2 app UUID'. The description says 'by its UUID' which reinforces the parameter's meaning. Since schema coverage is complete at 100%, the baseline is 3. The description adds minimal value beyond the schema—it doesn't clarify UUID format (e.g., standard UUIDv4) or where to obtain it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'details of a specific OAuth2 application' with its identifier 'by its UUID'. It distinguishes the purpose adequately from siblings like oauth2_clients_list (which lists) and oauth2_clients_create/update/revoke/rotate_secret (which mutate). Loses a point because it doesn't explicitly name the alternative sibling tools, though the phrasing is clear enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you need details of a specific OAuth2 app given a UUID. It doesn't explicitly state when to use this vs oauth2_clients_list or when not to use it. With a single existing sibling (oauth2_clients_list for listing and scopes for scopes), the context is reasonably inferable but not explicitly articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the burden. The description discloses the purpose and mentions fields returned (slugs, names, descriptions, default colors) plus the intended downstream use. However, it doesn't disclose pagination, whether companyId changes the returned set, or any other behavioral details beyond listing. Acceptable but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both carry information — first states what the tool returns, second gives actionable guidance on using the result. No wasted words. Slightly front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description adequately covers the purpose, return fields, and how the returned data connects to other tools (slug for updating config). The downstream guidance provides useful context for the config workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — companyId is the only param and the schema already describes it as 'Company UUID (overrides configured default)'. The description doesn't add much about this parameter beyond what the schema already states, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'List all available PDF template designs' with specific fields (slugs, names, descriptions, default colors). Distinguishes from siblings pdf_template_config_get/update/preview which operate on the configuration, while this lists available template design options. Slightly less explicit on whether it's tied to a company or global.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Some context is provided — says to use the slug when updating template configuration, which implicitly links to pdf_template_config_update. However, it doesn't explicitly state when not to use this tool or compare against the get/preview siblings, leaving the distinction mostly 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It states this is read-only listing and returns paginated results, which conveys the safe, non-destructive nature. However, it doesn't disclose default pagination values (which the schema does cover for page/limit), ordering defaults, or any company-selection behavior beyond 'selected company'. The pagination mention adds value, but more context on defaults or scoping behavior would strengthen this.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that covers purpose, scope, filtering capabilities, and return behavior. No wasted words, and it fits an appropriate length for a list endpoint. Could mention pagination defaults but it's already efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with 100% schema coverage, all 10 optional parameters, and no required fields, the description covers the essential behaviors: scope, filters, and pagination. With no output schema and no annotations, it does enough to define what the agent should expect. The main gap is not listing which status enum values exist, but that's documented in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds 'client' and 'search term' filtering vocabulary and 'paginated results' context but does not add meaningfully beyond the schema's per-parameter descriptions. All 10 parameters are already documented in the schema with descriptions, so the description doesn't need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List proforma invoices' with specific scope ('for the selected company') and lists filter dimensions (status, date range, client, search term). This distinguishes it from related tools like proforma_invoices_get (singular retrieval) and invoices_list (for invoices, not proforma invoices). Slightly generic on the verb side but the resource + scope is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (listing proforma invoices in the current company context) but does not explicitly state when NOT to use it or name alternatives such as invoices_list or proforma_invoices_get. It does convey the central context (company-scoped listing), but lacks explicit exclusions or alternative guidance which would improve decision-making for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It reveals what data is returned (status, timestamps, recipient information), which offers useful behavioral context. However, it does not disclose whether this is a read-only operation (no mutation warning needed) or any pagination/limits on the history returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, complete sentence that delivers the purpose and the key returned fields with zero filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only history-retrieval tool with 100% schema coverage and no output schema, the description reasonably covers the core purpose. However, since there is no output schema, the description must carry what the response looks like — it lists the fields (status, timestamps, recipient) but doesn't mention pagination or ordering, and lacks any exclusionary guidance versus sibling email-history tools (invoices_email_history, delivery_notes_email_history).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters ('UUID of the receipt' and 'Company UUID (overrides configured default)'). The description adds no parameter-level guidance beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves email sending history for a receipt, with a specific verb ('Get') and resource ('email sending history'). It distinguishes from its sibling candidates like receipts_email, receipts_email_defaults, invoices_email_history, and delivery_notes_email_history by specifying 'for a receipt' and listing the data returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the tool to call when you need a receipt's email history (as opposed to receipts_list, receipts_get, receipts_email). However, it does not explicitly state when NOT to use it or name alternative tools like invoices_email_history for invoice email history. The context is reasonably inferable but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. The description discloses that it toggles active status but doesn't reveal what happens to existing invoices in progress, whether the pause prevents future generation only or affects already-scheduled invoices, or any side effects. For a mutation operation with no annotation coverage, more behavioral context is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero wasted words. The active=true/false mapping is front-loaded and concise. Every sentence earns its place, and the structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A mutation tool with no annotations, no output schema, and a clear bulk API. It covers the core semantics but lacks behavioral details about failure handling, partial success, or impact on ongoing invoice generation. It's adequate for a simple bool-toggle operation, though a note on atomicity/partial failure would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all three parameters (ids, active, companyId) well. The description reinforces the ids and active semantics ('active=true to resume or active=false to pause') which adds a tiny bit of value but largely duplicates schema descriptions. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource combination ('Toggle the active/paused status of multiple recurring invoices') and clearly distinguishes this bulk operation from sibling tools like recurring_invoices_toggle (singular), recurring_invoices_update, and recurring_invoices_bulk_issue_now. The description unambiguously states what action occurs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by describing the action but doesn't explicitly state when to use this vs recurring_invoices_toggle (single) or recurring_invoices_update. It also doesn't note that this is a bulk alternative or whether partial failures occur. Context is reasonable but lacks explicit alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Get' implies a read-only operation, which is reasonable, but the description doesn't explicitly state it's non-mutating, what response structure to expect, or any auth/permission requirements. For a clearly read-oriented tool, this is adequate but leaves some uncertainty around return format and any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that states the purpose and scope efficiently. It's front-loaded with the primary action ('Get detailed information') and adds the line-item template context. No wasted words or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-record retrieval tool with 100% schema parameter coverage and no output schema, the description provides adequate context. It clarifies what is returned (detailed info plus line items as template). It could benefit from stating the absence of mutation, but given the read-oriented nature implied by 'Get', this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both uuid and companyId having descriptions. The description itself mentions 'specific recurring invoice template' and 'including all line items', which maps to the uuid parameter's purpose. Since the schema already documents both parameters fully, the description adds limited additional semantic value beyond context around the template's role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves detailed information about a specific recurring invoice template, including line items. It uses a specific verb+resource structure ('Get detailed information about a specific recurring invoice template'). It distinguishes from siblings like recurring_invoices_list (which lists all) and recurring_invoices_update/delete (which mutate), though it doesn't explicitly name them. The mention of line items used as a template adds useful scope detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a retrieval-use case ('Get detailed information') without explicitly stating when to use this versus recurring_invoices_list. It does clarify that it returns line items that serve as a template for generated invoices, which provides context. However, it offers no explicit alternatives or exclusions, and doesn't state when this should be preferred over other recurring_invoice tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description does disclose the key replace-semantics for lines (helpful), but it doesn't mention auth requirements, whether this is a partial vs full update for non-lines fields, idempotency, or validation behaviors that would apply when invalid field combinations are submitted. For a mutation tool with 25 parameters, this is a thin disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two sentences, front-loading the core purpose first, then the most critical usage constraint (partial update + lines replacement). Zero wasted words; every sentence earns its place. Excellent structure for a 25-parameter tool where the schema handles the field details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 25 parameters, no output schema, no annotations, and high schema coverage, the description covers the key update semantics (optional fields, at-least-one, lines replacement). However, it doesn't mention validation constraints between related fields (e.g., referenceCurrency requiring bnr_rate and RON currency), which are documented only deep in the schema's nested lines description. For such a complex update tool, additional guidance on cross-field dependencies would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema_description_coverage is 100%, so the schema fully documents all 25 parameters. The description adds marginal value by noting the fields are optional with at-least-one requirement and that lines replace existing lines. This matches the high-coverage baseline of 3, as the schema carries the heavy lifting and the description adds only modest augmenting information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing recurring invoice template with a specific verb+resource. It distinguishes from siblings (recurring_invoices_create, recurring_invoices_delete, recurring_invoices_toggle) by focusing on updating a template. However, it doesn't explicitly name alternatives like recurring_invoices_bulk_* tools for batch operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states that all fields are optional but at least one must be provided, which is an important usage constraint. It also clarifies partial-update semantics for the lines array (entire array replacement). This provides clear usage context but doesn't explicitly discuss when to prefer this over recurring_invoices_delete+create or the bulk variants.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so description carries the burden. It discloses 'soft-delete' (non-permanent) and that it returns a count of deleted items and errors. However, it doesn't explain what 'soft-delete' means for later visibility/restoration, partial-success semantics (partially deleted?), or whether the operation is atomic. Given zero annotations, this is a moderate gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. Front-loaded with the core purpose, followed by a useful return-value note. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has 2 params (100% schema coverage) and no output schema. Description explains it returns count and errors, which is useful. For a mutation tool with no annotations, it could disclose more about soft-delete implications (recovery, filtering in list endpoints) and error-handling behavior. Competent but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both ids and companyId described in schema. The description adds 'Returns count of deleted items and errors' context but not parameter-specific meaning. Baseline 3 is appropriate since schema fully documents parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Uses specific verb 'soft-delete' with resource 'multiple suppliers in a single request'. Clearly distinguishes from suppliers_delete (single). The word 'soft-delete' adds precision indicating non-destructive behavior, differentiating from a hard delete concept. Description is clear but doesn't explicitly contrast with siblings in the text itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States it handles multiple suppliers in a single request, implying use for batch deletions. But no explicit guidance on when to choose this vs suppliers_delete, nor any batch-limit context (maxItems 100 in schema helps). No exclusions or alternative tool named. Adequate but minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It does disclose that the delivery is recorded in history and that it's synchronous with immediate outcome return. However, it doesn't state whether a successful response is required, what happens on failure, or any permission/authorization requirements. For a tool performing an outbound network action, additional transparency about side effects would strengthen this.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly-worded sentences with zero wasted content. Front-loads the primary action, then adds the payload characteristic, then prerequisite and side-effect. Every sentence earns its place with concrete information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a test/diagnostic tool with no output schema, the description could explain what the returned outcome looks like, how to interpret success vs failure, and how it relates to delivery history. The requirement that the webhook must be active is mentioned, which is useful, but without annotations or an output schema, more detail on the return value semantics would improve completeness for a tool that's explicitly about returning an outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all three parameters. The description adds the context that eventType overrides the default webhook.test and that companyId overrides an env var, which adds some meaning beyond the schema. However, the description doesn't explain how to determine a valid webhook endpoint UUID or the relationship between companyId and the uuid parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it sends a synchronous test delivery to a webhook endpoint and returns the outcome, specifying it uses a synthetic webhook.test event payload. It's specific about verb (send), resource (webhook endpoint), and behavior (returns outcome immediately). However, it doesn't explicitly distinguish from sibling tools like webhooks_deliveries or webhooks_delivery_detail, though the 'synchronous test' nature inherently separates it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (to test a webhook endpoint before or during setup) but doesn't explicitly state when NOT to use it or mention alternatives like webhooks_deliveries for viewing past delivery history. The requirement that 'the webhook must be active' provides some usage context but there's no exclusion guidance against sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full transparency burden. It does disclose that this is a read operation (Get) and mentions the Business plan entitlement aspect, which is useful context. However, it doesn't describe pagination, potential errors, or what happens if the org isn't entitled — reasonable for a simple config-getter. Given no annotations and no output schema, a 3 is fair — it conveys the core behavior but no failure/edge-case context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the primary purpose ('Get the organization's white-label branding configuration'), and efficiently enumerates the returned fields. Zero waste, every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter configuration getter with no output schema, this description is reasonably complete. It tells the agent what data comes back (entitlement, app name, logo URL, accent color, Storno branding removal) which is the primary missing context. It could optionally enumerate exact field names for the return payload, but given no output schema exists this is already decent coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters and schema description coverage is 100% (empty schema). With no params, there's nothing to document, so this scores favorably. The description compensates for the empty schema by describing what will be returned, which is the relevant semantic content here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets the org's white-label branding configuration and enumerates the returned fields (app name, logo URL, accent color, Storno branding removal). It's specific with verbs and resources. However, it doesn't explicitly distinguish from its sibling white_label_config_update or white_label_config_verify_domain, though the read-only nature is implied by 'Get'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description identifies the Business plan requirement and lists returned data, which gives some context on when the results matter, but provides no guidance on when to use this vs siblings (like white_label_config_update for modifying, or verify_domain). No alternative tools are named or exclusions given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose a meaningful behavioral outcome ('On success the domain becomes active for client links'), which is useful state-change information. However, it doesn't disclose failure behavior, polling semantics, or whether it's idempotent. For a zero-annotation tool, the description adds moderate value but misses failure-mode transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action, minimal waste. The DNS record format and the success outcome are efficiently conveyed. Could arguably be slightly more compact, but every clause adds meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a 0-parameter verification action with no output schema. The description explains what it does and the success outcome, but doesn't address what happens on DNS-not-yet-published (does it fail? poll? return a status?). Given no annotations and no output schema, the description should disclose the non-success path more explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100% (trivially, since there are no parameters to describe). Per the rubric, 0 params = baseline 4. The description correctly explains that the domain comes from a previously-set operation ('returned when the domain was set'), so the agent understands the parameterless contract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Verify) and resource (custom domain via DNS TXT record), and clarifies the DNS record name format (_storno-verify.<domain>). It distinguishes from white_label_config_get/update siblings by focusing on verification specifically. It doesn't explicitly contrast against sibling tools but the verification action is distinctly conveyed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a post-setup verification step ('when the domain was set'), suggesting it should be called after white_label_config_update set a domain. However, it doesn't explicitly state when-not to use it, prerequisites (e.g., DNS record should already be published), or how it relates to retrying or error conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose key behavior: it lists the status values (pending, processing, completed, failed) and explains the output includes a download URL when complete. However, it does not mention whether this is a read-only operation, whether it polls/blocks or returns immediately, or any other side-effect behavior. The description adds some value but leaves 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences of zero-waste content. The first sentence states the purpose and outputs, the second lists all status values. Efficient and front-loaded with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple status-check tool with a single required parameter, well-documented schema parameters, and no output schema. The description clearly conveys what a caller should expect (progress, current step, download URL, status values). It is complete enough for an agent to invoke and interpret results, though it could note the download URL only appears on completion as a side note. A 4 fits given the tool's low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with both parameters (id and companyId) documented in the schema. The description itself adds no new parameter-level semantics beyond what the schema already states. Per the baseline rule with high coverage, a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (get) and resource (backup job status) and adds useful specifics about what's returned (progress percentage, current step, download URL). It doesn't explicitly differentiate from sibling tools like backup_download or backup_restore_status, but the status-related purpose is reasonably distinct. A 4 is appropriate since it lacks explicit sibling differentiation but is otherwise clearly specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool returns and lists the possible statuses, which implies when it would be used (checking on an in-progress backup job). However, it does not explicitly say when NOT to use this vs backup_download (which fetches the completed backup) or backup_restore_status (which tracks restore jobs). The context is clear but no exclusions or alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states this is a mutation tool (create) but doesn't disclose whether the operation is idempotent, whether duplicate names/TINs are rejected, what happens on validation failure, or whether required fields beyond name may be enforced conditionally. No return value or confirmation behavior is described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact at two sentences with the core purpose upfront. It efficiently covers the main value proposition and cross-references helper tools. Slightly more behavioral detail could justify a 5, but the current structure is clean and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 22 parameters (high complexity) with no annotations and no output schema. The description covers the creation intent and type distinction well, but lacks disclosure of edge cases (duplicate detection, type-conditional validation, what the created client object looks like on success). For a CRUD create of this complexity, more completeness would be expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the relationship between company type and auto-fill tools, and groups params conceptually. However, it doesn't add meaning beyond the schema for individual parameters (e.g., what enforces type-conditional CNP vs CUI requirements).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new client, explicitly supports both company and individual types, and names the specific helper tools (clients_anaf_lookup, clients_from_registry) that can auto-fill company details. This distinguishes it well from related tools like clients_update and clients_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit context: it mentions the tool is for manual creation and points to lookup tools (clients_anaf_lookup, clients_from_registry) for auto-filling data before calling. It doesn't explicitly state when NOT to use it versus other client tools, but the 'manual creation' framing provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description explains WHAT data is returned but does not disclose read-only status, potential authorization/permission requirements, error behavior for a nonexistent UUID, or whether the invoice statistics computation carries any cost/latency. For a read operation with zero annotation coverage, more transparency would be warranted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, front-loaded with the primary action. One sentence effectively communicates the tool's purpose and return content. Alias examples like 'detailed information about a specific client' are clearly explained.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-resource read endpoint with 100% schema coverage, the description covers the essential purpose and return content well. It names the invoice summary statistics and the recent-invoices list explicitly. However, given no annotations and no output schema, additional disclosure about error cases (nonexistent UUID) or the 10-invoice cap rationale could improve completeness, but this is reasonably adequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both uuid and companyId documented in the schema. The description adds context about the companyId as an override via the schema ('Company UUID override (uses active company if not set)'), but the description itself does not add parameter meaning beyond the schema. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') plus resource ('detailed information about a specific client by UUID'), and distinguishes itself from siblings like clients_list (which lists clients) and clients_get is clearly the detail/read variant. It also specifies the scope of returned data (invoice summary stats + 10 most recent invoices), making it unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage for fetching a single client's detail with invoice statistics, but does not explicitly state when to choose this over clients_list or provide alternative guidance. The distinction is implied by 'specific client' vs the list sibling, but no explicit when/when-not guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided for this tool, so the description carries the full burden of behavioral disclosure. This is a read operation (get history), which is inferable from the description. However, it does not disclose behavior details such as whether the email history is paginated, ordered by timestamp, what happens when there are no emails, or any permissions required. For a read-only history tool the behavioral surface is relatively small, so the lack of additional disclosure is a moderate gap rather than critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states the action, the resource, and the fields returned (status, timestamps, recipient information). There is no waste or filler. It is appropriately front-loaded with the verb and resource. It could arguably add a bit more behavioral context, but for what it includes, it is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only history retrieval tool with 2 well-documented parameters (100% schema coverage) and no output schema, the description is reasonably complete. It names the resource (delivery note), the scope (email sending history), and the data fields returned. The tool's complexity is low—no nested objects, no enums—so the description covers the essential context. A minor gap is the absence of guidance on ordering, pagination, or empty-result behavior, which would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (uuid = UUID of delivery note, companyId = company UUID overriding configured default) are already documented in the schema. The description reinforces that 'uuid' refers to the delivery note being queried. The description adds the contextual meaning that history is scoped to a single delivery note, reinforcing the parameter's role. Given the full schema coverage, the baseline 3 applies; the description provides slight additional context connecting the parameter to the history query, warranting a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Get') and resource ('email sending history for a delivery note'), with the scope being 'all sent emails with their status, timestamps, and recipient information.' This distinguishes it from sibling tools like delivery_notes_email (which sends) and delivery_notes_email_defaults (which manages defaults). The purpose is clear and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the tool to use when wanting to review sent email history for a delivery note, which is reasonably inferable from the name and description. However, it does not explicitly state when to use this vs alternatives, nor does it note any exclusions or prerequisites (e.g., no emails sent yet, requires the delivery note to exist/be issued). It also doesn't distinguish from the analogous receipts_email_history or invoices_email_history beyond the naming.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the informative detail that the delivery note is created in draft status, which is genuinely useful behavioral context. However, with no annotations provided, the description carries the full burden and there is no coverage of authorization requirements, reversibility, or side effects on the source proforma (e.g., does the proforma get marked as converted?).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact, information-dense sentences with zero redundancy. The behavior, inputs, and output state are clearly summarized efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no annotations and no output schema, so the description must cover behavioral context. It does state the result (draft delivery note, copied fields), but omits potential edge cases and preconditions (e.g., whether the source proforma must be in a valid state, what happens on repeated calls, relationship to delivery_notes_convert). Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 nothing about the parameters beyond what the schema states. The required proformaId is well-documented in the schema, but the optional companyId (which overrides configured default) is only documented in the schema with no further context about when it would be needed. The description provides no additional parameter insight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (create) and resource (delivery note from proforma invoice), and explicitly enumerates what gets copied (client, lines, dates, currency, notes). It distinguishes itself from the sibling delivery_notes_create by specifying the source is an existing proforma invoice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the use case: converting/existing proforma to delivery note. However, it does not explicitly state when to choose this over delivery_notes_create, nor does it mention prerequisites like whether the proforma must be in a certain status (accepted, issued, draft).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the return includes 'validation result with errors and warnings', which discloses output shape. However, no annotations are provided, so the description carries full burden. It doesn't disclose whether this is a read-only operation (likely is, but unstated), whether validation is blocking, or what happens on failure. The errors/warnings disclosure adds moderate value but leaves the mutation-safety question open.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no wasted words: purpose, what it checks, return shape, and usage timing. Front-loaded with the core purpose. Informative and efficient, though the return-format sentence could arguably merge with the purpose sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a validation tool with 2 simple params and no output schema, the description is reasonably complete. It explains the purpose, checks performed, return content, and usage workflow. However, no output schema means the agent can't know the exact return structure beyond 'errors and warnings', and the validation types are listed without elaboration on what they each entail. Adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters documented (uuid as 'UUID of the delivery note to validate' and companyId as override for default). Because the schema already describes both parameters, baseline 3 applies; the description adds no additional parameter context beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool validates a delivery note against Romania's e-Transport schema, listing specific validation types (entity, XSD, Schematron). It distinguishes from submit_etransport by positioning as a pre-submit check. Could be slightly stronger in noting this is a validation-only (non-submitting) operation but the specific verb+resource+scope is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The final sentence explicitly says 'Use this before submit_etransport to catch issues early', naming the sibling tool it pairs with and providing timing guidance. It doesn't explicitly state when NOT to use it or list alternatives, but the workflow positioning is clear and helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reasonably discloses that templates support dynamic variable replacement and that creating a default template may affect other templates (implied by isDefault semantics). However, it does not cover output/return behavior, permission requirements, or what happens if a default already exists for a category.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary purpose ('Create a new email template'), then secondary details about variables and category defaults. Every sentence earns its place with no padding. Slightly more could be added but it is adequately compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 6 parameters, full schema coverage, and no output schema, the description is reasonably complete for usage. It could benefit from noting whether templates are company-scoped, what happens when setting a default when one already exists, and behavior around Markdown/variables. These are meaningful gaps for a tool that agents may call when managing email configuration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents all 6 parameters. The description adds value by explaining dynamic variable behavior and the category enum options, but the schema descriptions for body, name, subject, companyId, and isDefault already carry most of the meaning. Baseline 3 is appropriate though the dynamic-variable explanation enhances subject/body understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates 'a new email template' and immediately explains the key feature (dynamic variables). It specifies the category parameter maps to document type with enumerated values. Distinguishes from sibling tools (email_templates_update/delete/list) by the 'create' action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the category parameter's use and default values, and implies a use case (creating templates that support dynamic variables). However, it does not explicitly state when to use this vs email_templates_update, nor mention prerequisites like whether a company context is needed or how defaulting interacts with existing defaults.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions that 'Templates support dynamic variables that are replaced with actual data when emails are sent' which adds behavioral context, and notes the category default. However, it doesn't disclose return format, pagination behavior, or whether companyId is required when no company is selected, which are meaningful 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences covering purpose, category filtering, and dynamic variable context — efficient and front-loaded with the core action. Minor redundancy with the schema's parameter descriptions but minimal waste overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple filtered-list tool with no output schema and only 2 optional parameters, the description covers the essential behaviors well. The dynamic variables context is a nice addition for understanding intent. It lacks return format info but that's acceptable given no output schema requirement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents both parameters well. The description reinforces the category values and default, which adds some value, and mentions companyId in the schema context. Since schema coverage is 100%, baseline 3 applies and the description provides marginal additive value about how these filter results.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all email templates configured for the selected company' with a specific verb (list) and resource (email templates), scoped to a company. It distinguishes from siblings like email_templates_create/update/delete by being a list operation. Could be improved by noting it's a read-only operation vs write siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains the category parameter for filtering by document type with default values, which provides context for when this tool is appropriate. It doesn't explicitly name alternatives or exclusion criteria, but the category filtering guidance gives reasonable usage context. Not quite a 5 because it doesn't explain when NOT to use this vs other template tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full behavioral burden. It discloses this is a listing/history operation and specifies the returned fields (job ID, type, source, status, row counts, timestamps). However, it doesn't clarify read-only safety, pagination depth, or how far back history goes, leaving behavioral transparency somewhat thin but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two clear, compact sentences front-loaded with the purpose ('List past import jobs') followed by precise return field enumeration. Zero wasted words, efficient and immediately readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a straightforward read-only listing tool with a clear scope (active company, optional override), explicit return fields, and both parameters fully documented in schema. While no output schema exists, the described fields cover the output contract. For an import-history listing across a large API surface, this is reasonably complete, only lacking pagination depth.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (limit, companyId) are fully documented by the schema. Baseline is 3 per the rubric. The description adds minimal beyond the schema—it confirms active-company default behavior ('active company') that aligns with the companyId parameter note. No additional semantic enrichment warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'List past import jobs for the active company.' The return fields enumerate exactly what is provided. It differentiates from the import tool family (import_execute, import_upload, import_preview) well by stating it's about history rather than execution. However, among the import_siblings it doesn't explicitly name an alternative, so not a full 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly conveys usage: this is for reviewing past import jobs via the return field list. The active-company scoping with companyId override is implied through the description and schema. However, it doesn't explicitly state when NOT to use it (e.g., to check current running import status, use import_get or import_execute) or name sibling alternatives for import flow states.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the mutation purpose ('Save column mapping') and that it confirms or adjusts mappings before execution, giving a sense of persistence. However, it doesn't disclose whether this is a write operation with side effects, whether it can be called multiple times (overwriting previous mappings), or any error/validation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that state purpose and then usage timing. Efficient and front-loaded with the core action ('Save column mapping'). Loses one point for not being maximally compact—the second sentence could potentially be merged, but it earns its place by adding workflow context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no output schema and no annotations, this is adequate but not complete. It explains the tool's role in the workflow and what it does, but omits behavioral details like idempotency (whether calling it repeatedly with different mappings overwrites), validation rules on columnMapping, and response/error expectations. It's a functional description that gets the job done without going beyond the minimum.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 3 parameters (id, companyId, columnMapping) have descriptions in the schema. The tool description itself does not add parameter detail, but the schema already documents the structure and the 'Storno fields' reference in the description gives semantic grounding for columnMapping's values. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb+resource: 'Save column mapping for an import job' and specifies it maps CSV columns to Storno fields. It distinguishes from siblings by being part of the import workflow (import_mapping vs import_preview, import_execute), though it doesn't explicitly name them as alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: 'Call after reviewing the preview to confirm or adjust mappings before executing.' This situates the tool in the import workflow sequence, telling the agent when in the process it should be called, though it doesn't explicitly name sibling alternatives like import_preview or import_execute.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses what data is returned (a timeline of various event types) but doesn't state whether results are paginated, ordered, filtered, or what the response structure looks like. Since this is a read-only tool, the lack of mutation warnings is less critical, but pagination/ordering behavior would add value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence that enumerates event types concisely and ends with a use-case sentence. It's lean with no repetition of schema/parameter details. It could arguably be split into two sentences for readability, but it's efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an audit/history retrieval tool, the description covers the key use cases (audit, debugging, lifecycle understanding) and enumerates the event categories. It doesn't have an output schema, but for a timeline tool the description adequately conveys what will be returned. It doesn't describe pagination or ordering, but this is a simple 2-parameter read tool, so completeness is reasonably high.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (uuid and companyId both have descriptions). The description adds meaning by clarifying what the tool does with the invoice and what kinds of events will appear. The schema already explains the companyId override behavior, so the description and schema are complementary. The description's enumeration of event types adds context that helps the agent understand what the uuid refers to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get the complete timeline of events for an invoice') and resource (invoice events). It enumerates the event types covered (status changes, ANAF submissions, validations, emails, payments, user actions). It doesn't distinguish from sibling alternatives like invoices_get or efactura_messages_list, but the 'events/timeline' framing is distinct enough among invoice tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful context about when to use ('audit trails, debugging, understanding invoice lifecycle history'), which implies the use case. However, it doesn't explicitly state when NOT to use it or contrast it with alternatives like invoices_get (which returns the current state) or efactura_messages_list (which covers a narrower event subset).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that it sends a live test message (a network/email side effect) and clarifies the override behavior and default recipient. However, it doesn't disclose whether this causes a sent email in history/logs, auth requirements, or what success/failure response looks like. For a test tool that sends real email, more behavioral context would be valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences that are direct and front-loaded, with the core purpose stated first. No wasted words, but the third sentence about recipient defaults could arguably be merged or clarified. Overall efficient and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 parameters with 13% schema coverage, no output schema, and no annotations. The description covers the core purpose and the override/default-recipient behavior but leaves gaps: what the test actually validates, how results are returned, and whether this sends a permanent email that appears in logs. For a multi-config test tool with zero annotation support, it's adequate but leans thin on edge case behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 13%, so the description must compensate. Only testEmail has a schema-level description. The description explains that parameters override saved configuration and that testEmail defaults to fromAddress, adding meaning to the host/port/username/password/fromName/fromAddress/encryption params. However, it doesn't detail the format/meaning of each parameter beyond the override concept, leaving 7 of 8 params mostly only defined by their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it sends a test message through the custom email sender to verify SMTP settings. It identifies a specific verb (send) and resource (test message via email sender). While there's a sibling storage_config_test and einvoice_config_test, the description's SMTP verification purpose is distinct enough to not need explicit sibling differentiation, though it could more explicitly separate itself from those.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it uses saved configuration unless overridden by parameters, and specifies the recipient behavior ('Sends to testEmail, or to the from address if omitted'). This gives clear when-to-use context for verifying SMTP settings. It doesn't explicitly state when NOT to use it or name alternatives, but the test+verify purpose is clear and self-contained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full disclosure burden. It mentions pagination behavior and the authentication scope, which is helpful. However, it doesn't disclose ordering of results, filtering options (or lack thereof), or whether read operations have side effects (e.g., marking as read). For a read tool this is acceptable but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and lists notification types efficiently. Every sentence earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple paginated list tool with 2 fully-documented parameters and no output schema, the description covers the essentials: what it returns, authentication scope, pagination, and content types. The notification type list is valuable context. Minor gaps: no mention of result ordering or whether unread notifications can be filtered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters (page and limit), with defaults and constraints already documented in the schema. The description adds the enumeration of notification types which enriches understanding of what the list contains, but doesn't add parameter-specific semantics beyond what the schema provides. Baseline 3 applies since schema fully covers parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a paginated list of notifications for the authenticated user. The verb 'Retrieve' plus resource 'notifications' establishes clear purpose, and the enumeration of notification types adds useful specificity. However, it doesn't differentiate from sibling tools like notifications_unread_count or notifications_mark_read, though the names themselves partially convey the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it returns a paginated list but doesn't explicitly say when to use this vs notifications_unread_count or other notification tools. The context of 'for the authenticated user' is clear, but there are no exclusions or alternative recommendations. The pagination parameters imply usage but no when/when-not guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. 'Update' signals a mutation operation, and the scope ('for the current company') is clear. However, it doesn't disclose whether updates are incremental (merge) vs. full overwrite, whether all 9 parameters are optional and only provided ones change (likely given 0 required params), or what validation errors might occur. For a config update tool this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single well-formed sentence that front-loads the core action ('Update the PDF template configuration') and then enumerates the customization scope efficiently. No redundant filler or repetition of schema details. It earns its length, though it could arguably be slightly more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 9 parameters, all documented in schema. There's no output schema, so the description need not explain return values. Given no annotations, the description could note partial-update semantics or idempotency, but for a config-update tool with fully documented parameters, this is reasonably complete. It falls short of full completeness because it doesn't clarify whether the update is a merge or replace of existing config.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — every one of the 9 parameters has a description in the schema. The description adds a general framing of categories (design, colors, fonts, logo, bank info, footer, custom CSS) but doesn't add meaning beyond what the schema already documents. The showVatInRon param in particular has a detailed legal rationale in the schema itself. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: 'Update the PDF template configuration for the current company' with a specific verb (update), a clear resource (PDF template config), and a comprehensive list of customizable elements (design, colors, fonts, logo, bank info, footer, custom CSS). It distinguishes itself from sibling tools like pdf_template_config_get (read), pdf_template_config_templates (list templates), and pdf_template_config_preview (preview).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it applies to 'the current company' and lists what can be customized, providing clear scope. However, it does not explicitly specify when to use this vs. the related config tools (get, templates, preview) or mention any exclusions or alternatives. The context is implied but not explicitly bounded.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It clearly conveys that fields are optional and partial updates are supported (omitted fields stay unchanged, color=null clears swatch), which is valuable behavioral context. However, it doesn't state return value, error cases, permission requirements, or whether updates are irreversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero wasted words. Front-loaded purpose, then key behavioral details. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update tool with 100% schema coverage, all parameters documented, no nested objects, and no output schema needed, the description effectively conveys the partial-update semantics which is the most critical behavior. It could mention return type or failure conditions but these are reasonably inferable. Adequate for the complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning the schema documents all 5 parameters. The description adds the partial-update semantics (omitted fields unchanged, color=null to clear) which adds value beyond the schema. With full schema coverage, baseline is 3, and the description adds modest additional behavioral context, so 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates a product category with a specific verb+resource. It doesn't distinguish from siblings product_categories_create and product_categories_delete, though the name 'update' makes the intent obvious among those siblings. It omits what fields are updatable beyond name/color implied.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for modifying existing categories (as opposed to create/delete siblings), but doesn't explicitly state when to use it or when not (e.g., required existence of the category, need for uuid). The guidance that 'omitted fields stay unchanged' and 'color=null to clear' is useful but it lacks explicit alternatives or preconditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It states the draft-only constraint and discloses it returns 'count of deleted and any errors,' which is useful. However, it doesn't describe failure modes (e.g., what happens to non-draft IDs — skipped or error?), partial-deletion behavior, or rollback semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, zero wasted words. Front-loaded with the verb+resource, followed by constraints and return info. Efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a batch-delete tool with 100% schema coverage and 2 params, the description is mostly adequate. It captures scope, eligibility, and return shape. But lacking annotations, it doesn't convey side effects beyond deletion (e.g., irreversible nature, cascading to related data), and doesn't clarify error handling for ineligible IDs, which matters for a bulk destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents both parameters (ids array and companyId override). The description adds little beyond schema — it restates the batch concept already in the name and schema. The draft-only qualifier adds domain context but doesn't clarify param behavior. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Delete multiple proforma invoices in batch.' Distinguishes from siblings (proforma_invoices_delete is singular). The phrase 'multiple...in batch' effectively separates it from the single-delete sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes 'Only draft proformas can be deleted,' which gives an important eligibility constraint. It doesn't explicitly name alternatives (e.g., proforma_invoices_delete for single), though the batch scope is implied by the name and description. No explicit when-not-to-use guidance beyond the draft restriction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the tool returns 'complete details' including calculated totals, which adds some value. However, it doesn't disclose whether this is a read-only operation (safe to call repeatedly), what happens if the uuid doesn't exist (error behavior), or any companyId scoping implications. For a retrieval tool with zero annotation coverage, this is a partial gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that communicates the tool's purpose and enumerates the content categories it returns. No filler, no repetition of the name/title, efficient and front-loaded with the key verb-resource pair.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-record retrieval tool with two well-documented parameters, this description is adequate. The tool's complexity is low, the schema covers parameters fully, and no output schema exists to require return-format documentation. The description covers what fields/data categories are returned, which is sufficient for an agent deciding whether to invoke it. It doesn't discuss authorization/permissions, but retrieval tools of this type typically don't need that depth for selection purposes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (uuid as receipt identifier, companyId as optional override). The description adds the notion of 'specific receipt' which reinforces the single-record intent of uuid but doesn't add format, scope, or constraint details beyond the schema. Baseline 3 is appropriate when schema carries the full parameter documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get complete details for a specific receipt' with a specific verb (get) and resource (receipt/bon fiscal). It enumerates what's included (line items, payment breakdown, fiscal data, calculated totals), which distinguishes it from siblings like receipts_list (list orientation) and receipts_update/delete (mutations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the detail/retrieval tool for a single receipt, contrasted with receipts_list for collections. However, it doesn't explicitly state when to use this versus receipts_get alternatives, nor does it note any exclusions or prerequisites (e.g., need for a uuid). The name and sibling structure make intent reasonably clear but there's no explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the return format (base64-encoded binary data) and the status precondition, which is genuinely useful context beyond the schema. However, it doesn't discuss whether this requires specific permissions, file size limits, or what happens if the receipt is in an unsupported status (error vs empty response).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the core purpose, return format, and the single important precondition. No wasted words. Slightly missing was explicit mention of what the tool returns on failure, but overall it's efficient and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description does reasonable work: it specifies return format, naming of the resource, and the required status precondition. However, for a data retrieval tool with zero annotations, it could say more about error conditions, whether the companyId parameter affects which receipt is returned, or other behavioral details. The two-parameter surface is simple enough that this is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with uuid described as 'UUID of the receipt' and companyId as 'Company UUID (overrides configured default)'. The description adds minimal parameter-level insight beyond the schema — the status precondition is a domain constraint rather than parameter syntax. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Download), resource (PDF for a receipt), and return format (base64-encoded PDF binary data). It distinguishes from siblings like receipts_get (which presumably returns structured data) and invoices_pdf by being receipt-specific. However, it doesn't explicitly contrast with other document download tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear precondition: the receipt must be in 'issued or invoiced' status, which is a useful usage boundary. However, it doesn't explicitly name alternative tools or state when NOT to use this tool beyond the status constraint, leaving some ambiguity about differentiation from related tools like receipts_get or invoices_pdf.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description does disclose an important side-effect detail — 'Does not update the nextIssuanceDate' — which is genuinely useful behavioral context. However, it doesn't address other behavioral aspects such as what happens on partial failure (some templates valid, some invalid), whether generation is transactional, or what happens to templates that have already issued invoices recently.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all of which earn their place: the primary action, the use case, and the important side-effect warning about nextIssuanceDate. There's minimal waste. It could arguably be more concise, but the disclosure about nextIssuanceDate is valuable and worth the extra sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an action-heavy mutation tool with no annotations and no output schema, the description covers the core purpose and a key behavioral caveat. However, it leaves gaps: no mention of error handling for mixed success/failure across multiple ids, no description of what the return value contains, and no indication of rate/limit behavior beyond the schema's maxItems constraint. Given this is a write operation with real consequences, more context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, covering both parameters (ids array and companyId). The description itself doesn't add parameter-specific detail beyond what the schema provides, but since the schema is fully covered, the baseline score of 3 is appropriate. No additional guidance on id format or expected behavior of companyId override is given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (generate), the resource (invoices from recurring templates), and the scope (multiple templates/bulk). The name and description together make it unambiguous. It also explicitly distinguishes this bulk variant from the single-template counterpart `recurring_invoices_issue_now`, which is a sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the purpose ('triggering generation outside the normal schedule'), which gives an implicit when-to-use. However, it doesn't explicitly mention the main alternative (recurring_invoices_issue_now for a single template) or when one should prefer the single version over the bulk version. It doesn't state exclusions or prerequisites either.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. The description is accurate and states the tool lists providers with config requirements and docs. It doesn't disclose edge cases (e.g., whether only enabled providers are returned, ordering, whether it requires auth). It's a low-risk read-only listing operation, so the missing detail is modest but notable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the verb 'List', zero waste. Slightly more detail on return contents would enrich it, but what's there is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list endpoint with no output schema, the description adequately covers what the tool returns and for what purpose. It's complete for its simple scope. Could mention whether it includes configured vs. all providers, but the simple nature of the operation justifies the brevity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema coverage is 100% with nothing to document. No parameter descriptions are needed since no parameters exist. The description's mention of what it returns (providers, config requirements, docs links) substitutes effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists available external storage providers and what they include (configuration requirements, documentation links). Clear verb+resource+result. Distinguishes from siblings like storage_config_get/update/test (which operate on a single config) and einvoice_providers/borderou_providers (different domains).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use guidance or alternatives mentioned. However, the purpose is self-evident as a discovery/list tool for providers, which is implied by the name and description. No exclusions or comparison to sibling tools provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The description indicates it's a read-only configuration retrieval ('Get... returns settings'), which is a non-destructive action. However, it doesn't disclose what happens if no config exists (returns defaults? error?), whether the operation requires special permissions, or the format of the returned data. The word 'Get' implies safe read behavior but no explicit safety statement is made.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that packs the resource, scope (active company), integrations, and content types. Zero waste, front-loaded with the verb and primary purpose. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (1 optional param, no nested objects, no output schema). The description adequately covers what the tool returns and the scope of the retrieval. Given the tool's low complexity, the description is reasonably complete. It could mention what happens when no configuration exists or whether defaults apply, but for a straightforward GET-style tool this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (single param fully described). The description adds meaningful context about the companyId param ('override uses active company if not set'), which clarifies the default behavior beyond the schema. This bonus context about the active-company fallback earns a 4 since it conveys semantic meaning not obvious from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Get') and resource ('accounting export configuration') and enumerates the specific integrations covered (Saga, Winmentor, Ciel) and what's returned (account codes, journal mappings, export preferences). This is specific and distinguishes it from update/config siblings, though the sibling accounting_export_settings_update is directly related but well-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it's a read operation for retrieving a company's export config, with the companyId param explained as an override. However, it doesn't explicitly state when to use this tool vs accounting_export_settings_update, when the active company is sufficient, or any prerequisites. No exclusions are given. This is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that settings are merged (not replaced) with existing config, which is a critical behavioral trait. It also discloses the company scope (active company) and the companyId override capability. The description is reasonably transparent for a config-update operation, though it doesn't state whether this requires special permissions or what happens on invalid config.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, tightly written with no filler. The key facts (update, merge, scope, targets) are front-loaded. Could arguably be one sentence, but the structure is efficient and each clause adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a config-update tool with 2 params (nested settings object), full schema coverage, and no output schema, the description covers the essentials: the update action, merge semantics, company scope, and supported target systems. A more complete description might mention permission requirements or error behavior, but for this tool's complexity the description is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (settings, companyId) are documented in the schema. The description adds context by explaining the merge behavior and the three target systems, which enriches the 'settings' parameter's meaning. The companyId override is also echoed in the description. This is adequate but not extensive beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates accounting export configuration with a specific verb (update) and resource (accounting export settings). It mentions the merge behavior and the specific systems (Saga, Winmentor, Ciel). However, it doesn't explicitly differentiate from the sibling tool accounting_export_settings_get, though the update-vs-get distinction is obvious enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (when updating accounting export config) and mentions the merge semantics (settings merged with existing config), which is useful guidance. However, there are no explicit when/when-not conditions or alternatives named, though the sibling accounting_export_settings_get provides an implicit contrast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses that a default organization is auto-created and that JWT tokens are returned, which is useful. However, it doesn't mention side effects like email verification requirements, rate limits, or what happens if the email is already taken (though schema notes 'must be unique'). Reasonable but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no filler. Front-loads the primary purpose, adds behavioral detail (organization creation, JWT return). Efficient and well-structured, though the JWT return could arguably be part of return-value documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-param registration tool with 100% schema coverage and no nested objects, this description is reasonably complete. It covers the core action, a side effect (default org), and the return type. Lacks some detail about post-registration flow (e.g., email verification), but is adequate for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented in the schema (email unique, password min 8 chars). The description adds the context of JWT return but doesn't add parameter-level semantics beyond schema. Baseline 3 is appropriate since schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Create a new Storno.ro user account'), clearly states what the tool does, and differentiates from siblings like auth_login and auth_register. The additional details about default organization creation and JWT tokens further clarify the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (registration flow, returns JWTs for subsequent authenticated calls) but does not explicitly state when to use this vs alternatives like auth_login (for existing users) or how this differs from auth_forgot_password/auth_reset_password. It's clear enough for registration but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses that the restore runs asynchronously, which is critical behavioral info, and prominently warns about purgeExisting deleting all current data. This is a destructive operation (implied) and the warning is clear. It doesn't mention return value or whether restore overwrites rather than merges, but the async note and destructive warning are substantial disclosures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core action, then async behavior and status companion, then a clear warning. The warning is appropriately placed at the end as a caution. No wasted words, though the warning could arguably be more prominent given the destructive potential.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description does well to disclose the async behavior, the status-check companion, and the destructive purgeExisting consequence. For a moderately complex tool (3 params, 1 destructive flag), this covers the essential operational contract. It could mention what happens to the ZIP after upload or whether a companyId override is required, but the core completeness is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are documented in the schema itself, giving a baseline of 3. However, the description adds meaning only to purgeExisting (via the warning) and largely ignores filePath and companyId. The warning adds genuine semantic value for one parameter, but the other two receive no additional context beyond schema. Since the description overlaps heavily with schema without adding much, this sits slightly below baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool uploads a backup ZIP to restore company data, with a specific verb+resource. It distinguishes from siblings like backup_create, backup_status, backup_download, and backup_restore_status by clarifying this is the restore action. Could be slightly more explicit about the restore being the inverse of backup_create, but the purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly identifies when to use this tool (to restore company data from a backup) and references backup_restore_status for checking progress, which orients the agent on the companion tools. It doesn't explicitly state when NOT to use it or name alternatives, but it does mention the async pattern and points to the status-check sibling, providing reasonable usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It identifies this as a read/list operation (the verb 'List' clearly signals non-mutating behavior), which is the core safety signal. It doesn't disclose whether provider availability changes, whether the companyId parameter affects results, or any rate-limit/caching behavior, but for a discovery/lookup endpoint the description is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with zero filler. The first sentence names the exact operation and resource, the second clarifies what is returned and why it matters. Nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list/discovery tool with one optional parameter and full schema coverage, the description is complete. No output schema exists, but the description pre-empts the need by stating what is returned (supported banks and file formats). The complexity is low, so nothing critically missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the lone parameter (companyId) is well-documented in the schema as a company UUID override. The description adds purpose context by clarifying how the result is used (bank statement import and reconciliation), which complements the schema. Since there's only one optional param and it's fully documented, minimal extra description is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource ('List available borderou providers') and explains what the tool returns (supported banks and file formats for bank statement import and reconciliation). It's distinguishable from siblings; while einvoice_providers and storage_config_providers exist nearby, the explicit 'borderou (bank statement)' context disambiguates it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used for discovering banks/file formats prior to borderou import or reconciliation, which is a reasonable context cue. However, it doesn't explicitly state when to use this against related tools like borderou_transactions or borderou_upload, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It explains grouping behavior (alphabetical) and filter capabilities, adding value beyond the raw schema. However, it doesn't disclose pagination behavior details, default sort beyond alphabetical, what happens if the active company isn't set, or response format since there's no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. Every clause adds information: what the tool does (list clients), the scope (active company), the grouping (alphabetical), and the filters (type, name, CUI/CNP, email). No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation with 5 well-documented params (100% schema coverage), the description covers purpose, grouping, and filters adequately. However, there's no output schema and no mention of pagination defaults or companyId override behavior in the description (only in schema). Given the tool's moderate complexity, it's adequate but could note that companyId override and pagination exist for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all 5 parameters well. The description adds contextual meaning by explaining the search fields (name, CUI/CNP, email) which maps to the 'search' param, and mentions 'companyId overrides active company' behavior is implied but not stated in the description—it's only in the schema. The description adds modest value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists clients for the active company, with specific details about grouping (alphabetical) and available filters. It distinguishes itself from sibling tools like clients_get, clients_create, etc., which are singular operations. However, it doesn't explicitly name a sibling alternative for listing clients, and there's no clients_list sibling that could be confused with it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly establishes it operates on the 'active company' (context) and explains the filtering/search capabilities. It doesn't explicitly state when NOT to use this tool or name alternative tools for other listing scenarios, but the context is clear enough for selecting this list tool over singular client operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description states the partial-update semantics clearly ('only the provided fields will be updated'), which is valuable. However, it doesn't disclose what happens if the UUID doesn't exist, whether the operation is reversible, or what the response contains. For a mutation tool with zero annotation coverage, more behavioral context would be expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste. It states the action, the key identifier (UUID), and the critical partial-update semantics. Every word earns its place, and it's front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a resource-update tool with 100% schema coverage and 23 well-documented parameters, the description adequately covers the essential context. The partial-update semantics are the most important missing piece the schema can't convey, and the description delivers it. No output schema exists, so return-value documentation could be useful, but it's not critical for an update operation. The main gap is the absence of failure/edge-case behavior (nonexistent UUID, validation errors), but the schema handles parameter documentation thoroughly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every one of the 23 parameters is documented in the schema with meaningful descriptions. The description adds the key semantic insight that all fields are optional in an update context — a critical detail not derivable from the schema alone (where only uuid is required). The description correctly emphasizes partial-update semantics, which adds real value beyond the structured schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing client by UUID' with a specific verb (update) and resource (client). It distinguishes from siblings by referencing the UUID-based update pattern, though it doesn't explicitly differentiate from related tools like clients_create or clients_delete. The purpose is clear but the sibling differentiation is implicit 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states that all fields are optional and only provided fields will be updated, which conveys the partial-update behavior. However, it provides no guidance on when to use this tool vs alternatives (e.g., clients_create for new clients, clients_sync_invoices for syncing). No exclusions or prerequisites are mentioned, such as whether the client must exist or permissions required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose the soft-delete nature and the cannot-delete-accepted constraint, which is useful. However, it does not explain what 'soft-delete' means for the agent (e.g., whether the declaration becomes hidden, restored via another endpoint, or affects downstream operations like lists/syncs).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero filler. Every word earns its place: the action verb, resource, soft-delete nature, and the key constraint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and only 2 params, the description is reasonably covering the basics. However, for a deletion operation it could explain what happens after soft-delete (recoverability, visibility, impact on related declarations like recalculate/sync), which would materially improve agent behavior in a system with many declaration lifecycle tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (id and companyId) are documented in the schema. The description adds no parameter-level detail beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Soft-delete a tax declaration') with a specific verb and resource. It distinguishes from siblings like declarations_recalculate, declarations_submit, declarations_validate by being the delete operation, and specifies the soft-delete semantic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes 'Cannot delete accepted declarations,' which gives a meaningful constraint on when the tool is usable. However, it does not explicitly state when to use this vs alternatives (e.g., there is no 'revert' or 'restore' pathway mentioned, and no guidance on whether soft-deleted declarations appear in lists or can be recovered).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It states this is a list operation returning paginated results with status and period, which communicates the read-safe nature. However, it doesn't disclose what happens without filters, whether deleted declarations appear, or ordering behavior. A 3 is fair given it establishes read semantics without deeper detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. It states the scope ('active company'), the filtering options, and the return content (pagination, status, period) efficiently. No redundant exposition or restating of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with well-documented schema (100% coverage, no output schema, no nested objects), the description covers the essential contract: what's listed, filtering, and return shape. It lacks detail on default behavior when no filters are applied, but with no output schema and straightforward params, this is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 all 7 parameters well (page, limit, type/status enums with allowed values, year/month ranges). The description adds the companyId override note about STORNO_COMPANY_ID env var via schema, and the description itself mentions filters by type/status/year/month, aligning with the schema. Since schema does heavy lifting, baseline 3 applies, but the description's reference to the filtering dimensions adds marginal value, warranting a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource combination: 'List tax declarations for the active company.' It clearly communicates the read-only nature and scope. It distinguishes from declarations_get (which retrieves a single declaration) but doesn't explicitly name it, so it earns a 4 rather than 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the listing tool within the declarations family and notes it supports filtering, but provides no explicit guidance on when to use it vs declarations_get, declarations_sync, or declarations_refresh_statuses. The 'active company' context is useful but no alternatives are named or exclusions given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. The description does state that it 're-populates data from current invoices,' which implies it modifies the declaration, but it doesn't disclose whether the operation is reversible, what happens to existing data before repopulation, whether it fails on non-draft declarations or silently no-ops, or what the response contains. For a mutation tool with zero annotation coverage, the behavioral transparency is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with zero wasted words. It front-loads the action, states the resource, and adds the critical status constraint. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description should disclose more behavioral detail. The core operation is clear (recalculate a draft from current invoices) and the draft-status constraint is stated, but the description omits what happens on invalid status, whether the recalculation is destructive to custom edits, and what the response indicates. However, the schema fully covers both parameters, so the description is adequate but not complete for a state-changing operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters ('Declaration UUID to recalculate' and 'Company UUID (overrides STORNO_COMPANY_ID env var)'). The description adds the drafting context but doesn't add parameter-level meaning beyond the schema. Notably, the companyId parameter mentions an env var override but no description text explains this anomaly. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Recalculate), the specific resource (a draft declaration), and the behavior (re-populating data from current invoices). It also distinguishes this tool from siblings by specifying the 'draft' status requirement, setting it apart from declarations_validate, declarations_submit, declarations_sync, and other declaration tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the tool only works on declarations in 'draft' status, which is a clear usage constraint. It doesn't name specific alternatives, but the 'draft' precondition effectively tells the agent when NOT to use this tool. The sibling set includes many declaration-related tools (validate, submit, sync, prepare) but no explicit when-not guidance is given, leaving some ambiguity for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does disclose key side effects: creates a new invoice, marks the delivery note as converted, and establishes a link. It also states return value. However, it doesn't disclose whether the operation is reversible, whether conversion is idempotent (can it be called twice?), or whether this is a final/irreversible state change for the delivery note. For a mutation-style conversion with notable side effects, this is a meaningful gap even if the primary behaviors are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first summarizes the action and its effects; the second states the return value. Zero wasted words, front-loaded with the core purpose, and all sentences earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description must carry more weight. It explains the core workflow and return value but lacks detail on edge cases: what happens if the invoice series is invalid, whether data can be customized during conversion beyond date overrides, and the irreversibility or state implications of marking a delivery note as converted. For a 5-parameter mutation tool with side effects, this is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all 5 parameters. The description adds no additional parameter-level insight beyond what the schema provides—the defaults for dueDate and issueDate are already stated in the schema. Since the schema fully covers all parameters, baseline 3 is appropriate; the description doesn't need to compensate but also doesn't add incremental value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Convert') + resource ('delivery note into a final invoice'). It enumerates the concrete effects: creates a new invoice, marks the delivery note as converted, and establishes a link between documents. This clearly distinguishes it from sibling conversion tools like receipts_convert_to_invoice and proforma_invoices_convert by naming the specific document type and workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but does not explicitly state when to use it vs. alternatives like delivery_notes_bulk_convert, proforma_invoices_convert, or receipts_convert_to_invoice. It doesn't mention exclusions or prerequisites (e.g., delivery note must not already be converted). The usage context is implied by the name and description rather than explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It's a read-only operation (fetching pre-filled content), which is implicitly clear. However, it doesn't disclose specifics like whether it mutates anything, whether template substitution depends on company config, or what side effects (if any) occur. For a seemingly harmless getter, moderate transparency is adequate, but it could state more about config dependence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that packs the full purpose — get pre-filled email content with recipient, subject, body, and template variables substituted. Zero waste, all relevant information front-loaded. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only default-fetch tool with 100% schema coverage and no output schema, the description is reasonably complete. It explains what's returned (recipient, subject, body) and the substitution behavior. Given the low complexity of this tool (2 simple parameters, no output schema), this adequately covers the usage scenario. Could mention it's a read-only preview, but the context is fairly well handled.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters (uuid of delivery note, companyId for overriding default). The description adds context that companyId overrides the 'configured default,' which maps conceptually to the 'default recipient' in the description. This provides meaningful added understanding beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets pre-filled email content (recipient, subject, body) with template variables already substituted for a delivery note. The verb 'Get' plus specific resource (delivery note email defaults) is clear. However, it doesn't explicitly distinguish from delivery_notes_email or delivery_notes_email_history siblings, though the name and description make the distinct purpose reasonably evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a preview/default-fetch tool, but doesn't explicitly state when to use it vs. delivery_notes_email (sending) or delivery_notes_email_history (prior emails). No explicit when/when-not guidance against alternatives is given. The 'pre-filled' language implies it precedes sending, but this is only implied, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description does disclose the full scope of returned data (which is useful behavioral info), but it doesn't mention safety, whether this requires read permissions, whether a missing/invalid UUID produces an error, or whether companyId override affects behavior beyond a hint in the schema. For a read-only getter, the description is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single informative sentence that front-loads the purpose (get complete details for specific invoice by UUID) and enumerates the returned data categories. Efficient and readable, though the data-category list is somewhat long; still earns its place since it signals the breadth of this tool versus lighter sibling getters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only detail-getter with 100% schema coverage and no output schema, the description adequately covers what data is returned and how to identify the target invoice. The list of returned categories compensates for the absent output schema to a reasonable degree, though it could note pagination/format of lists or error behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (uuid and companyId). The description adds the ANAF/XML/PDF detail context but no per-parameter semantics beyond schema. Baseline 3 is appropriate when the schema carries the description burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves complete details for a specific invoice by UUID, listing all returned data categories (line items, payment history, events, attachments, client/supplier info, XML/PDF status, ANAF submission). The verb+resource+scope is specific and distinguishes it from siblings like invoices_list (which is a list operation) and specialized getters like invoices_events or invoices_attachments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the tool to fetch full invoice detail by UUID, and the name (invoices_get) pairs with siblings like delivery_notes_get and proforma_invoices_get, giving context. However, there is no explicit when-to-use vs alternatives guidance, no mention of prerequisites (e.g., needing an active company), and no exclusions distinguishing it from invoices_list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly discloses that the password is never returned, which is important behavioral transparency. However, it doesn't disclose auth/permission requirements, rate limits, or error behavior, though for a GET config tool the risk profile is lower. The password disclosure note is valuable and earns more than a 2.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose in the first sentence, then a specific detail (returned fields) and a critical caveat (password never returned). Zero waste, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only config tool, the description is largely complete. It enumerates the returned fields since there's no output schema. It could mention error cases (e.g., if config not set up), but for this simplicity level the coverage is strong. The description adequately compensates for the missing output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema coverage (all params documented since there are none). The description enumerates the returned fields (host, port, encryption, username, from address/name, password-saved flag, last test time), which is useful since there's no output schema. This goes beyond what the empty schema provides, justifying above baseline. Not a 5 because it lacks return type/format details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Get the organization's custom email sender (SMTP) configuration'. It specifies the resource (SMTP/mailer config) and plan scope (Business plan). Distinguishes from siblings like mailer_config_update and mailer_config_test, and from similar config tools (storage_config_get, pdf_template_config_get). Not a full 5 because it doesn't explicitly name sibling alternatives, but the purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the plan requirement (Business plan), which implies when it's applicable. However, it doesn't explicitly contrast with mailer_config_update/test or mention when NOT to use it (e.g., not for free plans). It implies usage context but provides no exclusions or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does enumerate what fields are returned (name, client ID, client type, scopes, status, creation date), which is useful. However, it doesn't disclose pagination behavior, sorting, or anything about authorization requirements for listing OAuth2 clients.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that communicates the purpose and the returned fields. Every element earns its place; no wasted words or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with no output schema, the description is reasonably complete. It states scope, purpose, and the specific fields returned. It doesn't address pagination or ordering, which could matter for a list endpoint, but for a simple listing tool the coverage is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing for the description to add beyond what the schema states. The baseline of 4 applies since there are no parameters to document. The description appropriately lists the returned fields, adding value beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('List all registered OAuth2 applications') with clear scope ('for the current organization'). While it's fairly specific, it doesn't distinguish from sibling tools like oauth2_clients_get or oauth2_clients_scopes, though the plural 'list' verb and 'all' scope implicitly differentiates it from the singular 'get' sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the context ('current organization') but doesn't explicitly say when to use this versus oauth2_clients_get or oauth2_clients_scopes. The usage is implied by the verb 'list' indicating enumeration, but no explicit alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose a meaningful behavioral trait: 'Only returns scopes the authenticated user holds' — which signals auth-dependent, filtered output. However, it doesn't disclose pagination, ordering, or whether results reflect live permission state vs cached data. The one disclosed trait is genuinely useful but thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action and scope, with the constraining behavioral detail appended. Every word contributes meaning, no filler or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list/reference tool with no output schema, the description covers the key aspects: what it lists, how it groups them, and the visibility constraint. The main gap is that it doesn't describe the return format structure (e.g., categories and scope identifiers), but for a lightweight reference tool this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and the schema coverage is 100% (the schema is empty with no properties). With no params to document, the description needs only to explain what the tool returns, which it does well. The baseline of 4 for zero-parameter tools is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List'), the resource ('all available permission scopes'), and the grouping behavior ('grouped by category'). It distinguishes from siblings like oauth2_clients_list (list clients) and oauth2_clients_get (single client). The purpose is clear, though naming the sibling alternative explicitly would push it to 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a reference/introspection tool used when granting scopes to OAuth2 applications, but doesn't explicitly state when to use it vs alternatives or provide exclusion criteria. A clear context is implied from the name and content, but no explicit when/when-not guidance is offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It discloses the return format (base64-encoded UTF-8 CSV with BOM) which is useful. However, it doesn't disclose that this is a data-reading operation versus destructive, doesn't mention rate limits, data volume implications, or that the CSV may need decoding by the caller.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. States the action, scope, and return format efficiently. Front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 1 optional param, no output schema, and no annotations. The description covers purpose and output format but lacks behavioral context (e.g., how many records returned, pagination or truncation concerns, whether results are large enough to require download handling). For a simple export with a well-described single param, this is adequate but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single companyId parameter, which is well described as 'Company UUID (overrides configured default)'. The description mentions 'active company' which adds context that the default company is the active one, consistent with the override semantics. The description adds modest value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (export) + resource (all suppliers) + scope (active company) + output format (CSV). It clearly distinguishes from siblings like suppliers_export_saga_xml (different format) and invoices_export_csv (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies it exports all suppliers for the active company, which creates a sensible default context. However, it does not explicitly address when-not to use it (e.g., for filtered exports, saga XML format, or clients vs suppliers), nor does it name alternatives like clients_export_csv or suppliers_export_saga_xml.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses that secrets are masked in the listing, which is important behavioral context for a read operation. However, it doesn't describe the return format (e.g., whether metadata like created_at, event subscriptions are included) or pagination behavior for a potentially large list. It mentions the X-Company header requirement, which is helpful auth context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences total, each earning its place: the purpose statement, the secret-masking behavioral note, and the auth requirement. No fluff, no redundancy, appropriate front-loading of the core intent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with one simple string parameter, no output schema, and no annotations, the description covers the purpose, auth requirement, and a key behavioral detail (secret masking). However, there's no mention of output shape (fields per webhook, pagination) which could matter for an AI agent consuming the result, especially given the absence of an output schema to compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — the single companyId parameter is documented in the schema. The description adds that it overrides the STORNO_COMPANY_ID env var, which contributes context beyond the schema. Since coverage is high and there's only one parameter, baseline 3 is appropriate with slight credit for the env var override clarification.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all webhook endpoints for the current company, with an explicit scope (company-scoped). It distinguishes from siblings like webhooks_get (which retrieves a single endpoint by ID), webhooks_create/update/delete (mutations). It's a clear verb+resource+scope statement, though it doesn't explicitly name its sibling counterpart webhooks_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the tool operates on 'the current company' and mentions the X-Company header requirement (companyId param or STORNO_COMPANY_ID env var). This gives clear context on when to use it — when you need a full listing of webhook endpoints. However, it doesn't explicitly state when NOT to use it or mention webhooks_get as the alternative for fetching a single webhook.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses the auth requirement (SUPER_ADMIN) and the return contents (account details, verification status, role, last login, org memberships). However, it doesn't mention rate limits, whether results are sorted/deterministic, or what happens without admin privileges. For a list/hidden tool with no annotations, this is adequate but missing some edge-case behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero wasted words. The first sentence states the action and scope, the second adds the auth gate and return-value summary. Front-loaded with the core action, and every clause adds distinct value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a paginated list tool with 5 well-documented parameters (100% schema coverage) and a clear return summary, the description covers the essentials well. No output schema exists, so the description's reference to specific return fields (role, last login, verification status, org memberships) is genuinely useful. The only gap is that it doesn't clarify default pagination behavior beyond what schema defaults imply, but that's adequately covered by the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 5 parameters (page, limit, role, status, search) are already documented in the schema. The description adds no additional parameter context beyond what the schema provides — it doesn't elaborate on, say, the exact status enum values or how search interacts with other filters. With full schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this lists all users on the platform with pagination and filtering, and specifies it's admin-restricted (SUPER_ADMIN only). It names 'admin_users' explicitly and distinguishes it from member-focused tools like members_list by indicating it's a platform-wide admin listing rather than organization-specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides the key usage context — SUPER_ADMIN only — and indicates it returns paginated/filtered user data. While it doesn't name alternative tools explicitly, the SUPER_ADMIN restriction and platform-wide scope clearly separate it from members_list, invitations_list, and auth_me among siblings. It doesn't state when NOT to use it, but the admin-only gate is a helpful constraint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the checks performed and states it 'Returns validation result with any error messages,' which clarifies the tool is a validation (likely read/idempotent) operation. It doesn't describe side effects, whether errors are thrown versus returned, or how strict the validation is, but the description is reasonably transparent about the validation nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero waste. Each sentence adds value: the first states the purpose, the second enumerates the specific checks, the third describes the return. Perfectly front-loaded with the verb and purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter validation tool with no output schema and no annotations, the description does a solid job: it names the three validation dimensions, states the return type ('validation result with any error messages'), and clarifies the CIF-specific scope. It could arguably detail what a 'validation result' looks like more concretely, but for the tool's simplicity this is well-covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — the single 'id' parameter is documented as 'The ANAF token ID to validate (integer ID from anaf_tokens).' The description adds the context that this is the token whose e-Factura access is being validated, but with only one required parameter fully documented in the schema, the description adds modest context referencing that the ID comes from anaf_tokens. This is adequate, not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Validate'), the resource (ANAF token), and the specific scope: 'has proper access to e-Factura for a specific CIF.' It explicitly enumerates the three checks performed (organization ownership, ANAF registry, e-Factura access permissions), distinguishing it from sibling tools like anaf_status, anaf_tokens, and anaf_sync_* which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is used when you need to verify e-Factura access for a specific CIF, which is clear context. However, it doesn't explicitly state when NOT to use it or name alternatives (e.g., anaf_token_creation, anaf_status for checking overall ANAF connectivity). The 'specific CIF' framing gives useful context but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the return contents (user, organization, memberships, subscription) but doesn't state whether this requires authentication, what happens if unauthenticated, or whether this is a pure read with no side effects. The read-only nature is implied but not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, concise and front-loaded. The first sentence states the primary purpose; the second clarifies the return structure. No wasted words, though the 'flat JSON' note adds mild value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter simple read tool, the description is reasonably complete. It names all return sections (user, organization, memberships, subscription). No output schema exists, so listing return fields is appropriate. Could be slightly richer about auth requirements but adequate for a simple profile-fetch tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema coverage (empty properties object), so there are no parameters to document. Per the rubric, 0 params baselines at 4. The description effectively conveys there's nothing to configure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves the current authenticated user profile, naming the specific resources (user, organization, memberships, subscription). It distinguishes from related auth_* siblings like auth_login/auth_register by explicitly being about the current authenticated profile, though it doesn't explicitly name any sibling alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool name 'auth_me' plus description implies usage when the agent needs current-user identity/session context. It distinguishes from auth_login/auth_register/auth_refresh by focusing on reading the current profile, providing clear context without explicit exclusions or alternative tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly states this is a download returning base64-encoded binary ZIP data, which is helpful. However, it doesn't disclose size limits, whether the data is large enough to require streaming, auth requirements for download, or how the base64 data should be decoded/handled. It also doesn't clarify what happens if the backup isn't in completed status (error behavior). For a binary-data-returning tool with zero annotations, more behavioral context is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. Every clause adds value: the verb+resource purpose, the return format (base64 ZIP), and the prerequisite status condition. This is appropriately concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a fairly simple operation (download ZIP by ID) with 100% schema coverage and two params. The description covers purpose, return format, and a key precondition. With no annotations and no output schema, it could add more, but given the low complexity the description is reasonably complete. The key missing piece is error/edge behavior for incomplete backups and any size/encoding considerations, but these are minor for a simple retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema documents both parameters (id as 'Backup job ID', companyId as 'Company UUID override'). The description adds minimal parameter meaning beyond the schema, but with full coverage the baseline of 3 applies. The description does clarify that the 'id' refers to a completed backup, which adds a small dimension. However, it doesn't elaborate on the companyId override behavior or clarify the relationship between the id and companyId beyond what the schema says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Download a completed backup') and clarifies the output format (ZIP, base64). It clearly states a prerequisite (must be in completed status). This distinguishes it from siblings like backup_status, backup_create, and backup_restore, and from exports_download. The purpose is specific and clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'The backup must be in completed status', which is a clear prerequisite/condition for usage. It implicitly tells the agent to check backup_status before calling this tool. However, it doesn't explicitly name an alternative or contrast with backup_status, backup_restore, or exports_download among siblings. The 'when to use' is reasonably clear but the 'when not to use / alternatives' is not explicitly addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It states the tool returns progress percentage and current step (behavioral output detail), which adds transparency. However, it's a read-only status check with no destructive behavior, and the description is adequate but doesn't elaborate on edge cases like non-existent jobs or completion states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero wasted words. Efficiently states purpose, return values, and relationship to sibling. Exemplary conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple status-lookup tool with one required parameter, full schema coverage, and no output schema requirement, the description is reasonably complete. It conveys return values and the sibling relationship. Minor gap: doesn't describe what terminal states look like or error behavior, but for this simple tool the description handles the essentials.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters documented (id as restore job ID, companyId as optional UUID override). The description adds no parameter details beyond the schema. Baseline 3 is appropriate when the schema fully documents parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool gets status of a restore job, returns progress percentage and current step, and references backup_status for comparison. This is clear verb+resource but doesn't fully distinguish from backup_status beyond the statement that it's 'specifically for restore jobs'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly references the sibling backup_status and clarifies the difference (restore-specific). This provides context for when to use this tool vs backup_status, though it doesn't explicitly say 'use this when X, use backup_status when Y'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the disclosure burden. It does disclose the aggregation structure (day buckets with opening/closing balances) and the 366-day cap, which is meaningful. However, it doesn't state whether this is a read-only operation, whether companyId scoping affects results, or the default date behaviors beyond what the schema already states. It adds the ledger-bucket structure context but could disclose more about return shape given no output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, followed by structural detail and a constraint. Every sentence earns its place—no filler, no repetition of schema fields. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only ledger listing tool with 100% schema coverage and zero required params, the description covers purpose, content structure, and range cap. It lacks explicit statement of return format (each day bucket shape is hinted but not fully specified), and with no output schema this could matter. However, the description is reasonably complete for a data-retrieval tool; only minor gaps remain around exact response structure and relationship to sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—all three params (to, from, companyId) have descriptions including defaults. The description adds the 366-day cap constraint which is relevant to the from/to range, but it doesn't elaborate on date format details or interaction between defaults. Baseline 3 is appropriate since the schema handles parameter meaning and the description adds modest supplementary context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb+resource: 'Daily cash ledger across the requested date range.' It details exactly what each day bucket contains (opening balance, chronological entries, totals, closing balance). Among siblings, cash_register_balance and cash_register_movements_list are related but distinct—this tool aggregates into a structured daily ledger, which the description conveys clearly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly conveys usage (viewing a daily ledger for a date range), and the 366-day cap is a useful constraint. However, it does not explicitly distinguish when to use this versus cash_register_balance (single balance) or cash_register_movements_list (raw movements), and it gives no exclusions or prerequisites. The 'Range capped at 366 days' gives partial context but no explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses that deletion is 'permanent' (irreversible action) and scopes what types of movements are eligible. However, it doesn't mention whether this requires special permissions, what happens if the movement is already referenced elsewhere, or side effects like cascade behaviors. The permanence disclosure is valuable but the description could say more about consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. The first sentence states the action and its permanence; the second scopes what cannot be deleted. Every word earns its place and the critical exclusion is front-loaded right after the core statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete-by-uuid tool with only 2 parameters, full schema coverage, and no output schema, the description is reasonably complete. It covers permanence (irreversibility), the valid target scope (manual movements only), and directs users elsewhere for receipts/invoice payments. A minor gap is the lack of error messaging or cascade behavior description, but these are less critical for a straightforward deletion endpoint with good schema documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (uuid as Movement UUID, companyId as Company UUID override). The description adds the 'manual cash movement' restriction on which uuids are valid, which is useful context beyond the schema. However, it doesn't explain the distinction between a manual movement uuid and receipt/invoice-payment uuids in practical terms. Baseline 3 with modest added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('delete') and resource ('manual cash movement'). It distinguishes itself from related operations by explicitly noting that receipts and invoice payments cannot be deleted via this endpoint. However, it doesn't explicitly distinguish from sibling deletion tools like cash_register_movements_update or the broader invoices_delete, though the 'manual cash movement' scope is reasonably clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-not-to-use guidance ('Receipts and invoice payments cannot be deleted via this endpoint — use their respective resources'), indicating that manual cash movements are the only valid targets. This is stronger than implied usage. It could be improved by naming specific alternative tools, but the guidance is clear enough for an agent to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses key side effects: generates XML, uploads to ANAF SPV, and begins async status polling (implying a multi-step async process that returns before submission completes). It also discloses state constraints (draft/validated only). This is reasonably transparent for a submission tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero wasted words. Each sentence earns its place: the workflow, the async behavior, and the state constraint. Highly front-loaded with the core verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a submission tool with 2 well-documented params, no output schema, and no nested objects, the description is largely complete. It covers the workflow, the async polling behavior, and the valid input states. It might benefit from noting error scenarios or what the initial return value indicates, but for this complexity level, it's adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 documented in the schema. The description adds context about the state requirement but doesn't elaborate on the id parameter's meaning beyond 'UUID to submit' or the companyId override behavior. Baseline 3 is appropriate since schema already covers parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Submit), resource (declaration to ANAF), and the workflow (generates XML, uploads to ANAF SPV, begins async status polling). It distinguishes from siblings like declarations_validate and invoices_submit by specifying the ANAF submission pipeline. However, it doesn't explicitly contrast with einvoice_submit or declarations_sync which are closely related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it works on 'draft' or 'validated' declarations, implying it requires a declaration to already be in one of those states. However, there's no explicit 'when-not-to-use' guidance or mention of alternatives like declarations_validate (which likely prepares) or declarations_sync (which might sync statuses). The async polling aspect is noted but prerequisites like ANAF token/SPV configuration are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses draft status creation and series auto-assignment behavior, which is useful. However, it does not disclose side effects (e.g., whether creating consumes a series number, validation constraints beyond schema, or permissions required). The draft-status disclosure and e-Transport field context are helpful but not comprehensive for a 41-parameter creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with the key purpose front-loaded in the first sentence. It includes relevant lifecycle context and series behavior. It is appropriately sized for a complex tool without being verbose, though it could condense slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a very complex 41-parameter tool with no output schema and no annotations, the description provides a reasonable overview but doesn't explain return values, validation outcomes, or e-Transport submission implications. Given the complexity (e-Transport BR code constraints referenced in schema), the description could benefit from noting that many e-Transport fields are conditional on opType, though the schema descriptions already capture this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 41 parameter descriptions exist in the schema. The tool description adds minimal parameter-level value beyond the schema, though it highlights deputy information for proof of delivery and the series defaulting logic. Given full schema coverage, baseline 3 is appropriate—the schema does the heavy lifting and the description adds a couple of contextual notes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear, specific verb+resource statement: 'Create a new delivery note in draft status.' It further explains it documents physical delivery and can be converted to invoices, distinguishing it from the sibling delivery_notes_update and related tools. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the tool creates draft delivery notes and mentions the deputy information requirement for proof of delivery. It doesn't explicitly name alternatives, but the convert/issue/update siblings imply lifecycle usage. The series auto-assignment behavior ('default series if neither provided') provides helpful context for when not to specify series params.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Explains the default currentNumber semantics (default 0 means first document gets number 1), which is valuable behavioral context. However, with no annotations provided, the description does not disclose write/safety characteristics, side effects, or permission requirements. It's decent but leaves behavioral burden unmet for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, front-loaded sentences with no wasted words. The uniqueness constraint, patterns, and default-number semantics are all genuinely useful. Slightly dense but efficient and relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 5 params and no output schema or annotations, the description covers the core purpose and the trickiest param (currentNumber). However, it omits behavioral details like return values, permission requirements, or consequences of errors (e.g., duplicates). Adequate but with meaningful gaps for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 5 params have descriptions), so baseline is 3. The description adds value by explaining the currentNumber default behavior and pattern examples for prefix, but companyId and active are fully covered by the schema already. Does not exceed baseline significantly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource ('Create a new document series') with an explicit uniqueness constraint (prefix unique per company and document type). Distinguishes itself from siblings by addressing series creation specifically, distinct from document_series_update, _set_default, and _delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete naming conventions and patterns ('FAC' for invoices, 'FAC2026' for annual series), plus the uniqueness requirement per company and type. No explicit when-not-to-use or alternative naming, but the practical context is strong and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It discloses key behavioral variance (ANAF vs other providers, conditional API submission based on credential configuration), which is meaningful context beyond the schema. However, it doesn't disclose what happens on success/failure, submission status polling, or rate limits for provider APIs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably compact, front-loading the core purpose and then enumerating providers and behavior. The provider list is slightly redundant with the schema enum but useful for the agent contextually. No extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema absent, no annotations, and 3 parameters fully documented. The description covers the provider matrix and the credential-dependent submission behavior, which is the key nuance. However, it doesn't explain the return format or how the agent would query submission status (e.g., via einvoice_submissions sibling), leaving a moderate gap for a stateful submission tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters (uuid, provider with enum+country mapping, companyId with default behavior). The description adds the credential-configuration caveat that affects provider behavior, but doesn't add format/syntax details beyond the schema. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb+resource (+provider). It lists all supported EU providers with country codes, which strongly differentiates from siblings like einvoice_config_*, einvoice_providers, einvoice_submissions, and invoices_submit. The purpose is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that ANAF uses the existing e-Factura flow while other providers generate country-specific XML and optionally submit via API if credentials are configured. This gives clear context on when/how submission works per provider, though it doesn't explicitly contrast with the alternative invoices_submit tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It correctly identifies this as a read-only preview operation (implicitly non-destructive) and describes what it returns (columns, sample data, mapping suggestions). However, it doesn't disclose potential failure modes, whether preview is expensive, or what happens if the job hasn't finished processing the upload.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, one for purpose and one for usage guidance. Zero filler, perfectly front-loaded with the most important information in the first sentence. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description's enumeration of return content (columns, sample data, mapping suggestions) partially compensates by describing expected output. However, with only 2 simple params and no nested objects, the complexity is low. It doesn't explain the relationship to import_mapping/import_execute or what the preview validates (e.g., whether it reports errors). Adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters (id and companyId). The description adds meaningful context by explaining the tool's output (detected columns, sample data, mapping suggestions), which helps the agent understand what the id parameter refers to in the context of previewing. Uses the term 'companyId' consistently with sibling tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Get a preview of an uploaded import job including detected columns, sample data, and column mapping suggestions.' This is a specific verb+resource with concrete deliverables. It doesn't explicitly distinguish from siblings like import_mapping/import_get, but the preview-specific role is reasonably clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'Use after uploading a file to review before executing,' which gives clear sequential context. It doesn't explicitly name alternatives like import_mapping or import_get or describe when NOT to use it, but the temporal guidance (after upload, before execution) is useful and distinguishes its position in the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the auto-email behavior, the 7-day expiration, and the OWNER restriction. However, it does not mention whether the sender must hold admin privileges, whether duplicates are rejected, or what happens if the email is already registered. For a mutation tool with zero annotations, some additional behavioral context (permissions required, idempotency) would strengthen it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero redundancy - each sentence adds a distinct fact (action, email behavior, roles/expiry). It's front-loaded with the core purpose and efficiently communicates all constraints. Slightly more could be stated about permissions but overall appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with full schema coverage and no output schema, the description covers the core facts: what it does, side effects (auto email), expiration, and role restrictions. However, it lacks guidance on permission requirements for the acting user and what the response/return value looks like. Given the relative simplicity of this tool, these gaps are moderate, not severe.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (email and role) well-documented in the schema itself. The description redundantly restates the role enum values but adds minimal value beyond the schema. The 7-day expiration and email-sending behavior provide context about expected inputs though. This is the baseline 3 for full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Invite), resource (new user), and method (by email), distinguishing it from siblings invitations_list, invitations_delete, and invitations_resend. The purpose is immediately clear and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes that an invitation email is sent automatically and that invitations expire after 7 days, giving clear context for when this is appropriate. The role enumeration (cannot invite as OWNER) provides an implicit constraint. It doesn't name specific alternative tools, but the sibling set (list/delete/resend) makes the differentiation fairly natural.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does reveal a useful behavioral trait: the account overrides (accountCash/accountBank/accountCard) override the chart-of-accounts, with defaults coming from stored SAGA settings. However, it doesn't disclose whether this is a read-only export, whether it outputs a downloadable file, whether it's destructive, or any side effects like triggering integrations. For an export operation with zero annotation coverage, more behavioral context would be valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, followed by essential override semantics. No filler, no redundancy with the schema. Every clause earns its place—the first sentence states what and why, the second explains the override mechanism and defaults.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a relatively simple tool (4 optional params, no nested objects, no output schema). The description covers the purpose, scope, target format, integration purpose, and override semantics. The only gap is that it doesn't describe the return value or output behavior (e.g., file download, XML string, status), which an agent would need to know without an output schema. But given the tool's moderate complexity, the description is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter (companyId, accountBank, accountCard, accountCash) already has a meaningful schema description. The description adds context by explaining how the account overrides work relative to stored defaults, which is genuinely valuable beyond the schema. However, since the schema already documents each parameter individually, the parameter-level contribution is modest—though the description does explain the relationship between overrides and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb + resource + output: 'Export supplier payments (plati) in Saga XML format.' It further specifies the scope ('all incoming invoice payments for accounting software integration'), which distinguishes it from sibling tools like invoices_export_saga_xml, invoices_export_receipts_saga_xml, and suppliers_export_saga_xml. The export target (payments vs invoices/receipts/suppliers) is precisely differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool (for exporting supplier payments in Saga XML for accounting integration), which is clear context. However, it does not explicitly state when NOT to use it or name alternatives—for example, it doesn't mention that invoices_export_saga_xml or invoices_export_receipts_saga_xml would be the alternative for other export types. The purpose is clear but exclusions/alternatives are not explicitly provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the read-only nature (returns errors/warnings), mode variations, and compliance targets (UBL Schematron, CIUS-RO). This is decent behavioral coverage, though it doesn't describe what a pass/fail result looks like structurally or whether validation modifies state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. Front-loaded with the purpose ('Validate an invoice'), then the return type, then the mode options. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a validation tool with a clearly specified enum parameter and good schema coverage, this is reasonably complete. It explains modes, compliance standards, and purpose. It could mention what happens on validation failure (abort vs return), but given no output schema and moderate complexity, the description covers the essentials.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all three parameters (mode, uuid, companyId). The description adds modest value by explaining the quick/full mode semantics and implying companyId as an override, but mostly repeats schema content. Baseline 3 is appropriate since the schema does the documentation heavy-lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (validate) and resource (invoice), plus the output type (list of errors and warnings). It distinguishes itself somewhat from siblings like invoices_issue/invoices_submit by framing as a pre-issue/pre-submit check, but doesn't name a specific alternative tool for validation, so it doesn't fully earn a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys when to use it ('before issuing or submitting') and explains the two modes (quick vs full) with their trade-offs (speed vs comprehensiveness). It doesn't explicitly exclude alternatives or name sibling validation tools, but the placement context is reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries some burden. It does disclose an important behavior: cancellation preserves historical record (non-destructive). However, it doesn't disclose side effects such as whether cancellation triggers notifications, whether notes/reason are mandatory, or what happens to associated records.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with zero waste. The first sentence states the core action, and the second adds the eligibility constraint and the key differentiator from deletion. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a cancellation tool with no output schema and no annotations, the description conveys the core purpose and constraints adequately. However, it could be more complete about what 'cancel' means in this domain — e.g., whether it affects VAT reporting, blocks further edits, or requires specific user permissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already documented in the schema. The description adds little beyond what the schema provides. It doesn't clarify, for example, whether cancellationReason/cancellationNotes are required in practice, or whether companyId must match the proforma's company.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Cancel a proforma invoice') and immediately adds the key distinction from siblings: it preserves the historical record unlike deletion. This clearly distinguishes it from proforma_invoices_delete, which is the primary alternative in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when it can be used ('from any status except converted or already cancelled'), giving clear eligibility constraints. It also implicitly differentiates from deletion by noting it preserves history, though it doesn't explicitly name the alternative tool or state when you'd prefer delete over cancel.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It clearly states a key consequence: once rejected, the proforma cannot be converted to an invoice. However, it doesn't disclose whether rejection is reversible, whether it requires permissions, or what happens to existing acceptance status if any. The one stated consequence is valuable but partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero wasted words. The critical consequence is stated in the second sentence without ceremony. Well sized for the operation complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, but the state transition (reject) meaning is fully captured by stating the permanent consequence. The 4 schema parameters each have descriptions at 100% coverage. For a state-changing action with no output schema, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all 4 parameters. The description adds minimal extra meaning beyond the schema—it mentions 'rejection reason and notes' but doesn't elaborate on formats, requirements, or how companyId's override works. With full schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (mark as rejected) + specific resource (proforma invoice) + clear actor (by the client). Distinct from siblings like proforma_invoices_accept, proforma_invoices_cancel, and proforma_invoices_convert—the rejection action is clearly differentiated from cancellation and acceptance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (when the client rejects a proforma) but does not explicitly contrast it with alternatives. Sibling tools like proforma_invoices_cancel and proforma_invoices_delete exist, but no 'use this instead of X when...' guidance is given. The state consequence provides some implicit guidance about when to choose this over cancel.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses the crucial 'replaces all line items' destructive behavior and the draft-status requirement, which are the two most important behavioral traits. However, it doesn't mention whether updates to non-draft invoices fail or are ignored, what happens to required fields if omitted, or any permission/authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with front-loaded purpose. Each sentence earns its place: the verb+resource, the draft status constraint, and the line replacement behavior. It's appropriately brief for a tool with a well-documented schema and doesn't repeat information already present in the parameter descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mutation tool with 23 parameters (8 required), the description covers the critical behavioral facets: the draft-status gate and the destructive line-item replacement. No output schema exists, so return-value details aren't expected. The description doesn't cover edge cases like partial updates (can notes be updated alone?) or whether all required fields must be re-sent, but given the schema's thoroughness, this is a reasonable trade-off.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 all 23 parameters thoroughly. The description adds meaningful value beyond the schema by explaining the 'lines' array replaces all existing line items, which is a semantic nuance not captured in the parameter description. It clarifies that the array semantic is full replacement rather than merge, which is high-value information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Update an existing proforma invoice') and adds the key behavioral constraint that only drafts can be updated. However, it doesn't explicitly distinguish from sibling tools like proforma_invoices_create, though the name itself makes the update-vs-create distinction clear. The draft-status restriction is valuable differentiator.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this is for updating existing invoices in draft status, which gives a usage boundary. It doesn't explicitly name alternatives (e.g., that proforma_invoices_create is for new invoices), but the draft-status precondition and the line replacement behavior together give practical usage guidance. It lacks explicit when-not-to-use exclusions or mention of related flows like convert or send.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that receipts are created in draft status and can be converted to invoices, plus the default series auto-assignment behavior. But it doesn't mention validation rules, permissions required, or what happens on success/failure beyond the implicit creation semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences covering purpose, lifecycle, and series behavior. Efficient and front-loaded with the core purpose. No wasted words, but could be slightly more structured given the 24-parameter surface area.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with 24 params and complete schema coverage, the description covers the essential purpose and lifecycle. It lacks guidance on relationship between payment fields (cashPayment/cardPayment/otherPayment vs paymentMethod), idempotency usage context, or edge cases like clientId vs customerName alternatives — though the schema descriptions partially cover these.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents all 24 parameters. The description adds context on seriesId vs documentSeriesId fallback behavior. It doesn't add meaning for paymentMethod, lines, or other parameters, but that's acceptable given complete schema coverage — baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear specific verb+resource: 'Create a new receipt (bon fiscal) in draft status.' Distinguishes from siblings by stating receipts document point-of-sale transactions, can be issued/converted to invoices, and noting default series auto-assignment. Well-defined scope that separates it from invoices_create and proforma_invoices_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies draft-status creation and later issuance/conversion path, giving context on the receipt lifecycle. States the default series behavior when neither seriesId nor documentSeriesId is provided. However, it doesn't explicitly differentiate from receipts_issue/convert_to_invoice or mention when receipts_create vs invoices_create is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the return content (current provider, bucket, region, connection status) which gives the agent a sense of what the operation reveals. However, it doesn't disclose whether this is read-only safety-wise, whether it requires admin permissions, or what failure modes exist (e.g., no config set). The description is adequate but not rich in behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. The first sentence states the core action and return fields; the second adds contextual value by explaining the feature purpose. Front-loaded with the primary action. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter GET config tool, the description is largely sufficient. It states what's returned and the feature's purpose. Minor gaps: no mention of what happens when storage config is not set (empty response vs error), and no indication of whether this requires any special permissions. But given the simplicity of the operation, these are minor concerns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has 0 parameters and schema already covers 100%. There's no parameter information needed since there are no params to document. The description's mention of what fields are returned (provider, bucket, region, status) is the relevant semantic content here, and it provides that. Baseline 4 for zero-parameter tools is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Get' with clear resource 'external storage configuration'. It enumerates the exact return fields (provider, bucket, region, connection status) and explains the feature's purpose (storing PDFs/XMLs in S3-compatible bucket). Differentiates well from sibling tools like storage_config_update, storage_config_test, and storage_config_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use guidance or alternatives mentioned. While it's a straightforward GET config operation, the description doesn't state when to prefer this over storage_config_test (which presumably tests connectivity) or how it relates to storage_config_providers. The return of 'connection status' blurs the line with a test operation. No exclusions or prerequisites stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose an important behavioral trait — that core ANAF fields are immutable — which is valuable. However, it doesn't describe the mutation's effect (partially updating only provided fields vs replacing), required permissions, or whether the operation is reversible, leaving gaps for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the purpose and immediately clarify the immutability constraint. Efficient with no wasted words, though it could mention null-clearing semantics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-param mutation tool with no annotations and no output schema, the description adds critical context (which fields are protected). However, it doesn't clarify partial-update semantics, null-clearing behavior, or response format, leaving meaningful gaps for a write operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter has a brief schema description. The tool description adds value by grouping params into categories (contact, address, banking, notes) and clarifying that updates are restricted to editable fields, but doesn't add syntax/format details beyond what the schema already documents. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Update editable fields of a supplier record.' It explicitly distinguishes from the broader supplier CRUD by enumerating which field categories are editable (contact, address, banking, internal notes) and explicitly excluding core ANAF data (name, CUI). This clearly separates it from sibling tools like suppliers_create and suppliers_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states what can and cannot be updated ('Core data (name, CUI) from ANAF cannot be modified'), giving the agent explicit constraints on when this tool is appropriate. However, it doesn't explicitly name alternative tools for modifying non-editable fields or mention prerequisites like the required uuid lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It mentions 'when authenticated' as a precondition, which is useful. However, it doesn't describe what the response contains beyond listing the diagnostic domains, nor does it disclose potential failure modes, latency implications, or whether this is a read-only operation. The description adds some value but doesn't fully compensate for the absence of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and covers purpose, scope, and usage context efficiently with no wasted words. It front-loads the core function. Slightly more detail on what the diagnostics contain or how to interpret them could add value, but the current structure is clean and effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple health-check tool with no parameters, no output schema, and no annotations. Given the low complexity, the description covers the essential aspects: what it checks, the authentication prerequisite, and the troubleshooting use case. It doesn't detail response format, but for a tool this simple with no parameters, the coverage is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema coverage, so there are no parameters to document. Per the rubric, 0 parameters earns a baseline of 4. The description adds no parameter-specific semantics since none exist, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks system health status for the Storno API and specifies the diagnostic areas (database, queue, storage, service). It's distinct from sibling tools like system_version, which handles version info. However, it doesn't explicitly distinguish itself from system_version or anaf_status siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes it's 'useful for troubleshooting connectivity or service issues,' providing a clear when-to-use signal. It doesn't explicitly exclude alternative tools but the troubleshooting purpose gives adequate context. No explicit exclusions or alternative tool mentions, but the intended use case is reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that this is a mutation toggling branding on/off and that disabling reverts to default branding. However, it doesn't disclose whether fields are independently patchable (partial updates), what happens with concurrent enable/disable states, or the authorization/permission requirements beyond the Business plan hint. The customDomain parameter's reset-verification side effect is disclosed in the schema, not the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact, single-sentence listing of the tool's purpose with an optional clarifying clause about the footer removal. Zero waste, no redundancy, appropriately front-loaded with the most important facts (white-label branding, Business plan).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update/configuration tool with 100% schema coverage and no output schema, the description plus schema covers the key behavioral aspects well. The main gap is the lack of a plan-qualification mention beyond 'Business plan only' and no guidance on how partial updates work, but these are minor gaps given the strong schema documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters are already documented in the input schema. The description adds a high-level summary of the configurable fields but doesn't add meaning beyond what the schema's per-parameter descriptions already provide (e.g., hex format, max chars, domain reset behavior are all in the schema). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this tool creates or updates the organization's white-label branding, listing the specific customizable fields (app name, accent color, toggle, footer removal). The Business plan requirement and 'Storno.ro' footer removal distinguish it from any sibling like white_label_config_get, making the purpose specific and well-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the Business plan restriction and notes the 'when off' behavior uses default Storno branding, giving some usage context. However, it doesn't explicitly state when to use this vs white_label_config_get or white_label_config_verify_domain, and doesn't provide guidance on sequencing (e.g., domain verification steps after setting customDomain).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the disclosure burden. It indicates this returns 'available' invoices (filtered/eligible candidates), which is useful behavioral context. However, it doesn't describe what 'available' means (unmatched? unpaid?), pagination, or what the result set looks like for a tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, information-dense sentence with zero redundancy. Every element earns its place: the purpose, the matching context, and the search criteria.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a lookup tool with no output schema, the description should hint at what results look like or what 'available' eligibility means. The params are fully documented, but the semantics of 'available' and the response shape are unaddressed. Adequate but with meaningful gaps for an agent deciding whether this finds the right candidate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema documents all 4 parameters well (id, type with enum, search, companyId). The description reinforces 'search by number, client name, or amount' which maps directly to the schema's search parameter hint. The description adds the default type behavior ('both') which isn't in the schema itself. This exceeds the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb+resource+scope: 'Get invoices or proforma invoices available to match against a borderou transaction.' It also specifies search dimensions (number, client name, amount). This is a narrow, well-defined lookup tool distinct from sibling list/get operations elsewhere.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for matching documents to a borderou transaction, which gives context for when to use it. However, it does not explicitly state when not to use it or name alternatives like invoices_list or proforma_invoices_list for broader listing needs. The guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool 'creates transactions' and 'runs automatic matching', implying significant mutation and potential side effects, but doesn't disclose whether the operation is reversible, whether it can create duplicate transactions if called twice with the same file, what happens on partial parse failures, or whether provider validation is required first. For a mutation-heavy tool with zero annotation coverage, this is a meaningful gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences with zero waste. The first sentence establishes purpose and formats; the second conveys the multi-step behavior (parse, create, match). Well front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter tool with no output schema and no annotations, the description explains the operation's effect well but doesn't address critical operational aspects: idempotency/duplicate risk for repeated uploads of the same file, what response/callback the caller receives (no output schema to clarify this), and whether provider must pre-exist via borderou_providers. These gaps matter for correct usage of a file-import mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so parameters are all documented in the schema. The description adds value by framing sourceType with its two enum meanings ('borderou' for payment lists, 'bank_statement' for bank exports) and clarifies the matching behavior against existing invoices. The description supplements the schema moderately beyond its baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb+resource ('Upload a bank statement or borderou file') and explicitly lists the supported file formats (CSV, XLSX, XLS). It distinguishes this from related tools like borderou_transactions and borderou_transactions_save by explaining this is the upload/import entry point for reconciliation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what happens after upload (parses file, creates transactions, runs matching against invoices), giving clear context on the tool's lifecycle role. However, it doesn't explicitly mention when NOT to use this vs alternatives like import_upload, borderou_transactions_save, or borderou_transactions_rematch, which are sibling tools with overlapping concerns.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It discloses a caching behavior ('Results are cached for 5 minutes'), which is useful. However, it doesn't disclose read-only status, rate limits, or behavior on no matches. The cache disclosure adds genuine value, but given zero annotation coverage, more behavioral detail would be warranted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding value: purpose, return format, use case, and caching. No waste or redundancy. Could arguably be more compact, but it's appropriately sized for what it conveys.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple schema (2 params, no output schema, no nested objects) and the description covers the purpose, return content, use case, and caching behavior. For a search tool of this complexity, this is reasonably complete. No output schema exists, so the description does state what's returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both params (q and limit) are already fully documented in the schema. The description adds minimal param-level detail beyond what the schema provides, which is acceptable given the high coverage. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Search the Romanian company registry by company name') and specifies what's returned (companies with CUI, name, registration details). It clearly distinguishes itself from sibling tools like company_registry_cities and clients_anaf_lookup by naming the ONRC registry specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context ('Useful for finding a company before creating a client') that indicates when to use it. It doesn't explicitly mention when not to use it or name specific alternatives like clients_anaf_lookup, but the stated use case provides reasonable guidance for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It does reveal key behaviors: the tool auto-populates from invoice data, aggregates by CIF and VAT rate, and supports specific declaration types. However, it does not disclose whether creation overwrites existing declarations for the same period, whether companyId is required or optional, what role ANAF validation/sync plays during creation, or the exact return value/outcome when successful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action and purpose. The first sentence establishes verb, resource, and behavior; the second adds supported types and aggregation logic. No wasted words. Minor deduction because it could be tightened by folding the type list into the schema reference since the input schema already enumerates the enum values.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 5 params (3 required), no output schema, and no annotations, the description does a reasonable job: it explains the creation behavior, supported types, and aggregation logic. However, it does not address whether a duplicate declaration for the same type/year/month is permitted, whether prior declarations must exist (dependencies), or what the response contains. Given the complexity of this domain (tax declarations with ANAF interactions) this is a moderate gap but not severe.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the structural baseline is 3. The description adds genuine value beyond the schema by explaining how 'type' relates to tax declaration forms, how the period (year/month) drives the aggregation window, and that companyId overrides the STORNO_COMPANY_ID env var (already in schema). The aggregation-by-CIF-and-VAT-rate detail clarifies the semantics of the period parameters. Minor deduction because periodType's meaning ('monthly' vs alternatives) is not elaborated, and the type enum values (d394, d300, etc.) are listed without explaining which form each represents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new tax declaration and auto-populate it from existing invoice data' — a specific verb (create) plus resource (tax declaration) plus behavior (auto-populate). It enumerates supported types and explains the aggregation logic by partner CIF and VAT rate. This distinguishes it from sibling declaration tools like declarations_submit, declarations_recalculate, and declarations_prepare.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what happens during creation (auto-population from invoices, aggregation by CIF/VAT rate for the specified period) which gives implied context about when to use it. However, it doesn't explicitly state when NOT to use this tool versus alternatives like declarations_prepare, declarations_recalculate, or how this differs from declarations_sync. The context is clear but exclusions and alternatives are not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of disclosure. It clearly states that the operation checks SPV messages, downloads recipise (a specific artifact), and returns 202 indicating async processing. This goes beyond a generic 'refresh' claim by describing the mechanism and async nature. It doesn't mention side effects or failure behaviors, but the described behavior is reasonably transparent for a status-refresh action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. Every phrase carries meaning: scope (all in-flight), source (ANAF), mechanism (SPV messages), side effect (downloads recipise), and async return code (202). No redundancy with the tool name or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description covers the triggering action, mechanism, scope, and async return. The use of unusual terminology like 'recipise' (likely a typo for 'recipisa'/receipt) without clarification is a minor gap, but overall the tool is adequately specified for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single companyId parameter, so the baseline is 3. The description adds meaningful context by noting that companyId 'overrides STORNO_COMPANY_ID env var', which explains the fallback behavior and when the parameter is needed vs optional. With only one parameter at full schema coverage, the added env-var context is a genuine bonus beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb (refresh), a specific resource (statuses for in-flight declarations from ANAF), and clarifies the scope (submitted/processing declarations). It distinguishes reasonably from siblings like declarations_sync, declarations_submit, and anaf_sync_trigger by focusing on refreshing statuses via SPV messages, though it doesn't explicitly differentiate itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for refreshing in-flight declaration statuses, which provides some usage context. However, it doesn't explicitly state when to use this vs declarations_sync or anaf_sync_trigger, nor does it mention exclusions or alternatives. The scope is directional (only submitted/processing declarations) but no explicit when/when-not guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the key behavioral constraint (only one default per type, and setting a new one presumably un-sets the previous default), but it doesn't mention whether this is a mutation requiring specific permissions, what happens to any previously-default series, or whether the operation is reversible. The side-effect of implicitly replacing the prior default is implied but not stated explicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding value: the action, the consequence of auto-selection, and the exclusivity constraint. No wasted words, though slightly more detail on the default-replacement behavior could have fit without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple state-setting tool with 2 params, full schema coverage, no nested objects, and no output schema, this description is largely complete. It conveys the action, the domain consequence, and the key invariant. It could mention the side effect on the previously-default series, but overall it's adequate 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (uuid and companyId). The description itself mentions 'its type' but doesn't add detail about how the type is derived from the uuid, nor does it elaborate on the companyId override behavior beyond what the schema states. Baseline 3 is appropriate since the schema handles the documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set a document series as the default'), the resource ('document series'), and adds meaningful behavioral context: the default is auto-selected when creating new documents of that type, and only one series can be default per type. This distinguishes it well from sibling tools like document_series_create, update, and delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the context of use ('auto-selected when creating new documents') and the constraint ('only one series can be default per type'), which implicitly tells the agent this tool is used to designate which series applies by default. It doesn't explicitly name alternatives or exclusions, but the domain context (siblings include series CRUD) makes the usage clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It says the tool 'Shows which providers are enabled and their settings', implying a read-only operation, and enumerates the exact config fields per provider. However, it does not disclose whether credentials are returned masked/full, whether the response includes non-enabled providers, or any auth requirements. For a list read tool this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph but efficiently packed with useful provider-specific field details. It could be restructured into separate sentences for providers, but every clause adds value (field names per provider are actionable). Slight room for improvement in scannability, but no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 1 optional parameter, no output schema, and no annotations, the description does a solid job of explaining what the returned configuration will contain across all five providers. It lacks details on response shape or masking of secrets, but for a list/read tool the content coverage is strong.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (companyId is fully described). The description adds that companyId uses a default when unspecified, which is behavior the schema does not convey. It also adds context about what the returned data contains. However, the description does not add syntax-level detail beyond what the schema already provides, though the default-company behavior is genuinely valuable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List'), resource ('e-invoice provider configurations'), and scope ('for a company'). It distinguishes itself from siblings like einvoice_config_save/delete/test and einvoice_providers by focusing on listing existing configurations with provider-specific settings. The description also enumerates all supported providers (anaf, xrechnung, sdi, ksef, facturx), which adds meaningful specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool vs alternatives, but the name einvoice_config_list versus einvoice_providers (likely listing available providers, not current configurations) creates an implicit distinction. It does say what is returned (enabled state, API credentials, routing codes), and lists provider-specific fields, but offers no explicit exclusions or alternative links.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral disclosure burden. It discloses the key behavioral trait that setting isDefault to true will unset the current default template in the same category—a critical side effect. It also clarifies the at-least-one-field requirement. This is strong for a system with zero annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with three concise sentences covering purpose, constraints, and side effects. Every sentence earns its place. Minor deduction for not structuring param semantics more explicitly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a non-destructive update tool with 100% schema coverage and no output schema, the description covers the essential operational concerns: the update target, the optionality constraint, and the default-category side effect. It's reasonably complete given its relative simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all 6 parameters. The description adds the 'at least one must be provided' constraint and the isDefault side-effect semantics, which go slightly beyond the schema. Baseline 3 is appropriate since schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing email template with a specific verb+resource combination. It's distinguishable from siblings like email_templates_create and email_templates_delete due to the 'existing' modifier and 'update' verb. However, it doesn't explicitly contrast with those siblings within the description itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance: it's for updating existing templates, and it explicitly notes that all fields are optional but at least one must be provided, which is important usage context. It also explains the isDefault behavior. However, it doesn't name alternative tools or explicitly 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose update frequency (daily ~13:00 EET), the return format (1 foreign currency = X RON), and the behavior on weekends/holidays (last available rates returned). This is meaningful behavioral context for a read-only data-fetch tool, though it doesn't detail data shape beyond the currency expression.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact three-sentence block with no fluff. It front-loads the source and purpose, then adds scoping details (update time, format, holiday behavior). Every sentence earns its place; no redundancy with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple single-optional-parameter read tool with 100% schema description coverage, so the description need not over-explain. It covers source, freshness, format, fallback behavior, and the optional date parameter is documented in the schema. The optional 'date' parameter is fully described in the input schema, and the description notes default to latest. Complete for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the single 'date' parameter has a clear description with format and default behavior). The description also confirms the latest-available default behavior. There is essentially nothing else to add beyond what the schema provides; baseline 3 applies since the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'Get' plus explicit resource 'current BNR exchange rates' clearly states what the tool does. It specifies the source (Banca Nationala a Romaniei), the currency convention, and the update cadence. While it doesn't explicitly name alternatives, within the sibling set it's distinguishable from exchange_rates_convert (a conversion tool) by its list/current-rates nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (fetch current or date-specific BNR rates) but does not explicitly state when to use this versus exchange_rates_convert or other alternatives. There are no explicit exclusions (e.g., 'use exchange_rates_convert for amount conversion'). The context of listing all currencies vs converting is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the return value is base64-encoded CSV with column headers and example rows, which is useful behavioral context. However, it doesn't mention the output size, whether it's a pure read operation (inherently implied by 'download'), or any format details beyond base64 encoding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. Front-loaded with the core action (Download) followed by return format and downstream usage. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple 2-parameter, 1-required tool with 100% schema coverage. The description adequately covers the return format, the download nature, and the relationship to import_upload. Given its simplicity, the description is largely complete; it could optionally note that no auth headers or size limits apply, but for a tool this simple this is well-covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are already documented in the schema (importType with enum values, companyId as company UUID override). The description adds the clarification that companyId is an override when active company isn't set, but the schema already conveys this. The description's main added value is explaining what the returned template contains.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Download) and resource (CSV template for a specific import type). It distinguishes this download/retrieval tool from the import execution siblings (import_execute, import_upload, import_preview) by making clear it just fetches a template.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states that the template is to be filled in and uploaded via import_upload, providing clear follow-up context linking to a sibling tool. It doesn't explicitly state when NOT to use it, but the coupling to import_upload gives adequate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the upload/creation behavior and the return value, which is reasonable. However, it doesn't disclose potential side effects (e.g., whether the import job runs immediately or requires subsequent steps), file size limits, or error conditions for invalid file types or mismatched sources. For a stateful workflow tool, this leaves some uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact—one focused sentence plus a returns clause. It front-loads the core action and formats, then lists allowed enum values inline. It's efficient, though the full enumeration of importType and source values duplicates what's already in the schema enums, making it slightly redundant even if convenient for the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a file-upload tool with no output schema and four well-documented parameters, the description provides the essential context: file formats, required param types, and the return value. The main gap is workflow context—how this tool connects to import_preview/import_mapping/import_execute in the import pipeline. Minor gaps include file size limits and behavior on invalid input, but overall adequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all four parameters documented in the schema. The description mentions importType and source as required and lists their allowed values, reinforcing the schema without adding deeper meaning. It adds a bit of context about file formats (CSV/XLSX/XML). Since coverage is complete, baseline 3 is appropriate—the description doesn't meaningfully extend beyond the schema for parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs and resources: 'Upload a file (CSV, XLSX, or XML) to start a new import job.' It clearly states what the tool does, what file formats are accepted, and what it returns ('Returns the created import job with preview data'). It distinguishes itself from sibling import tools like import_preview, import_execute, and import_mapping by focusing on the upload/start-new-job action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the purpose ('to start a new import job') and enumerates the valid importType and source values. It mentions the return value. However, it doesn't explicitly address when NOT to use this tool or how it relates to related import workflow steps (import_preview, import_mapping, import_execute), which would aid a multi-step import workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the export scope (all outgoing invoice payments), the account override mechanism, and the card leaf analytic requirement. However, it doesn't disclose whether this is a read-only operation, side effects, output location, or how exported data is delivered (download, stored object, etc.), and lacks detail on what happens to existing exports or the format of the generated file.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences covering purpose, scope, parameters, and a domain-specific requirement. The information is front-loaded with the core purpose first. The only slight inefficiency is the parenthetical '(incasari)' which adds a Romanian localization note, but it's arguably useful domain context. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description carries substantial burden. It covers purpose, scope, parameters, and a domain constraint. Missing elements include return/delivery details (how the exported XML is returned or stored) and explicit distinction from sibling export functions, but for a moderately complex export tool with 4 well-described parameters, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter having a clear description (companyId, accountBank, accountCard, accountCash). The description adds meaningful context on top by explaining the override purpose and the SAGA leaf analytic requirement for cards. However, the description adds moderate value beyond the schema—it frames the purpose but doesn't add significant new semantics beyond what each parameter description already conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource combination: 'Export payment receipts (incasari) in Saga XML format... Exports all outgoing invoice payments for accounting software integration.' It clearly differentiates from siblings like invoices_export_saga_xml and invoices_export_payments_saga_xml by explicitly naming the format and scope (outgoing invoice payments for accounting integration).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use it (accounting software integration) and how to use the override parameters, including the important SAGA-specific requirement that cards require a leaf analytic like 5125.2. However, it doesn't explicitly state when NOT to use it versus the closely-related invoices_export_saga_xml or invoices_export_payments_saga_xml siblings, which would be valuable given the naming similarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It discloses scope ('active company'), return shape ('paginated results with totals'), and filter dimensions. However, it doesn't disclose behavior for edge cases—e.g., what happens when companyId override is set, pagination limits beyond what schema states, or whether active company defaults apply silently. Lacks depth on read-side behavior like ordering defaults or total field semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both earn their place—first establishes the core purpose and capabilities, second details filter dimensions and return structure. No wasted words, front-loaded with the primary action. Slightly verbose in listing every status value within the description (already covered in the enum), but that redundant enumeration is minor.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list/query tool with 11 parameters, 100% schema coverage, no nested objects, and no output schema, the description is reasonably complete. It covers filters, pagination, sorting, scope default, and return structure (totals). Missing details like ordering default (desc) and limit cap (100) are already in the schema, so the description doesn't need to repeat them. The return 'totals' mention partially compensates for the lack of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 11 params documented in the schema). The description adds a valuable semantic layer by grouping filters into categories (status/direction/date range/client/search) and stating 'active company' default behavior that clarifies companyId override semantics. Enums clarify status/direction values. The description's grouping helps the agent map parameters to intent, exceeding the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource ('List invoices') with explicit scope ('for the active company') and thorough enumeration of capabilities (pagination, filtering, sorting). Distinguishes from siblings like invoives_get (single retrieval), invoices_export_csv (export), and proforma_invoices_list (different resource type).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description states it lists invoices for the active company and iterates available filters, which clarifies common use cases (status, direction, date range, client, search). However, it doesn't explicitly say when NOT to use this tool versus related alternatives (e.g., when to use export_csv vs list, or how it differs from proforma/recurring lists). Guidance is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose the 'validated' status requirement and Pro plan requirement. However, it doesn't describe the return value/outcome format (e.g., what a passed vs. failed verification returns), or what happens if the invoice is not yet validated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: what it verifies, what checks it performs, and the usage prerequisites. Zero waste, front-loaded with the core purpose first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is moderately complex (verification with three distinct checks), has no output schema, and no annotations. The description covers purpose, prerequisites, and the scope of verification adequately. However, it lacks detail on the verification result/return format, which matters for a verification tool where the agent needs to interpret pass/fail outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both uuid and companyId are already documented in the schema. The description adds the constraint that uuid 'must be ANAF-validated', which reinforces the parameter context beyond the schema's 'Invoice UUID' note. This is baseline 3 given full coverage; the description adds only marginal reinforcement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool verifies the ANAF digital signature on a validated invoice, specifying the three checks it performs: certificate validity, signature cryptographic integrity, and XML content integrity. This is a specific verb+resource combination that distinguishes it from siblings like invoices_validate and anaf_sync_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states prerequisites: requires Pro plan and the invoice must be in 'validated' status (ANAF-signed). This gives clear context for when the tool is applicable. It doesn't explicitly name alternatives or exclusions, but the prerequisite specification effectively guides usage versus other invoice tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations were provided, so the description carries the full burden. It accurately discloses the destructive nature by explaining the consequence: documents will revert to the default Storno address. This explains the key behavioral outcome (the config is permanently removed, reverting to default behavior) without over-explaining. For a destructive config-deletion tool this is sufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no wasted words. The first states the action; the second states the consequence. Front-loaded with the core purpose. Zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema destructive tool, the description is complete. It states the action, the resource affected, and the behavioral consequence. Sibling tools exist (mailer_config_get/update/test, storage_config_delete for a parallel delete pattern) but this deletion tool doesn't need more context given its simplicity and the clear consequence statement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters (no input schema properties), so there are no parameters requiring documentation. The description correctly reflects this by making no mention of parameters. Baseline 4 for 0-parameter tools is appropriate here since there's nothing to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: deletes the organization's custom email sender configuration. The verb 'Delete' plus the specific resource ('custom email sender configuration') gives clear purpose. It doesn't explicitly differentiate from sibling tools like mailer_config_get/update, but the delete semantics are self-evident from the name and the sibling set is large enough that the name itself is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear operational consequence ('Client documents revert to being sent from the default Storno address'), which conveys when this tool is appropriate versus keeping the custom config. It doesn't explicitly state when NOT to use it or reference alternatives like mailer_config_update, but the consequence statement provides meaningful decision context for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the mutation behavior and important constraints (cannot set role to OWNER, cannot modify organization owner). The 'null to reset to role defaults' detail adds behavioral nuance. However, it doesn't disclose what happens to existing permissions when role changes, whether deactivation cascades to sessions, or whether allowedCompanies is additive or replacement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, efficient, no filler. The description front-loads the core purpose and packs constraints efficiently. Slightly denser than a two-sentence ideal but every sentence carries meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and no annotations, the description reasonably covers the action, constraints, role enum, and permissions reset semantics. It's adequate. Small gaps on default behavior for omitted optional fields and whether allowedCompanies replaces the list, but these are not critical for a member update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each of the 5 parameters already documented in the schema. The description adds value by clarifying the permissions null-reset behavior and enumerating valid roles, but these largely restate schema info (the role enum matches schema, the null option is already in the schema's anyOf). This aligns with the baseline 3 for high schema coverage where description need not duplicate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (update), the resource (a member), and enumerates the specific fields that can be modified (role, active status, allowed company access, custom permissions). It distinguishes from siblings like members_delete and members_list through its specific verb+resource+field list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on role constraints ('Cannot change role to OWNER or modify the organization owner') and how the permissions parameter behaves (array vs null to reset). While it doesn't name alternative tools explicitly, the restrictions and parameter semantics give the agent enough context to use it correctly among the members_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses it's lightweight/suitable for polling, which implicitly signals read-only behavior. However, it doesn't describe the return format (e.g., does it return just a number, or an object with total/filtered counts?), auth requirements, or any rate-limiting considerations for polling frequency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with zero waste. The first states the core purpose, the second adds the polling use-case context. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only count endpoint, the description is largely sufficient. The main gap is the lack of return format disclosure (number vs object), but this is a simple tool and the 'get count' framing reasonably implies a numeric response. No output schema exists, so a note on return type would improve completeness slightly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are 0 parameters and schema coverage is 100%, so there's nothing for the description to add about parameters. The baseline of 4 for zero params is appropriate since there's no parameter ambiguity to resolve.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource ('Get the count of unread notifications') and specifies the subject scope ('for the authenticated user'). It distinguishes itself from sibling tools like notifications_list (which lists notifications) and notifications_mark_read, though it doesn't explicitly name them as alternatives. Clear enough but not maximal differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states this is a 'lightweight endpoint' and is 'suitable for polling to update notification badges', providing clear context for when to use it. It implies this is efficient for repeated calls. However, it doesn't explicitly state when NOT to use it or name alternative tools like notifications_list for full details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose key behaviors: it creates a new invoice, marks the proforma as converted (a state change), and links the two documents together. It also discloses the return of both objects. However, it doesn't state whether the operation is reversible or destructive to the proforma, whether the proforma's status precludes conversion (e.g., already converted), or what happens to the linked state afterward.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero wasted words. It front-loads the primary action and then covers the side effects and return value efficiently. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core flow well (create, mark, link, return). No output schema exists, but the return value is described ('both the new invoice and updated proforma'). However, it lacks details on edge cases relevant to a conversion: preconditions (is the proforma required to be in a certain status?), what happens if the proforma is already converted, and whether conversion can be undone. For a multi-effect operation, a bit more on preconditions and failure semantics would be valuable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 adds value by clarifying the overall conversion flow, and the schema properties themselves have good descriptions (override dates with defaults, series override). The description doesn't add param-specific meanings beyond schema, but the schema is already comprehensive, so this is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Convert'), the resource ('proforma invoice into final invoice'), and the exact behavior: creates a new invoice with all proforma data, marks proforma as converted, and links the two documents. This distinguishes it from sibling proforma tools (create, accept, reject, cancel) and is very specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (when you want to convert a proforma into a final invoice). However, it doesn't explicitly state when NOT to use it or name alternatives (e.g., delivery_notes_convert, receipts_convert_to_invoice exist as sibling converters). There are no exclusions, prerequisites, or mention of related conversion tools for other document types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It clearly discloses side effects: creates a new invoice, marks the receipt as invoiced, and establishes a document link—all beyond what a casual reader might expect from a convert operation. It also states the return value (both new invoice and updated receipt). This is strong behavioral transparency for an un-annotated mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact two-sentence structure that front-loads the primary purpose and then adds behavioral detail (marks receipt as invoiced, establishes link, returns both documents). Every sentence carries substance with no filler or redundancy. Slightly less crisp than ideal since it could arguably be one tighter sentence, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a state-changing conversion tool with no annotations and no output schema, the description covers the operation's mechanics, side effects (receipt invalidation/marking), and return value. The 5 parameters are all documented in the schema at 100% coverage. It could mention prerequisites or side effects like whether the original receipt becomes non-editable, but for the available context it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 with no param info needed. The description references the main uuid parameter implicitly ('the receipt') but does not explain the optional parameters (dueDate, issueDate, invoiceSeriesId) beyond the schema. However, the schema already provides clear descriptions for all 5 parameters, so the description adds no meaningful extra semantics. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Convert an issued receipt into a final invoice') and clearly explains the transformation. It distinguishes itself from siblings by describing the conversion action which differs from create/delete/issue operations on receipts and the related proforma_invoices_convert and delivery_notes_convert tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the input is an 'issued' receipt, implying it must already be issued, which offers some usage context. However, it does not explicitly say when to use this tool versus alternatives like invoices_create or other convert tools, nor does it explain what happens if the receipt is not in an issued state or cannot be converted. No exclusions or failure conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It explains the state transition (cancelled → draft) and that cancellation is reversed, which is useful. However, it doesn't disclose side effects like whether restored receipts regenerate document numbers, affect accounting/ANAF sync, or impact refunds, which would be valuable for a financial document mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded purpose, zero filler. Every word earns its place: state transition, precondition, and consequence all conveyed efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a state-transition tool with 2 simple parameters, full schema coverage, no output schema, and a focused purpose, the description is mostly adequate. The gap is behavioral context: no mention of whether restoration is reversible, how it interacts with accounting/AFIP sync, or what validation might fail (e.g., if the receipt was already converted or issued). Given the financial domain, slightly more context would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with both parameters described clearly in the schema itself. The description adds no parameter-level detail beyond schema, so with full coverage this is baseline 3. The uuid is self-explanatory as 'UUID of the cancelled receipt to restore', and companyId overrides default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource+state transition: 'Restore a cancelled receipt back to draft status.' It also notes the precondition (only cancelled receipts can be restored) and the outcome (re-issuable). This clearly distinguishes it from sibling tools like receipts_cancel, receipts_delete, and invoices_restore.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly communicates the precondition 'Only cancelled receipts can be restored' and the re-issuance outcome, which gives context for when this tool applies. However, it does not explicitly state when NOT to use it or name alternative tools for other statuses (e.g., receipts_delete for permanently removing), though the precondition narrows scope well.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Locks the SUPER_ADMIN role requirement, which is a security/authorization disclosure. Lists what data comes back (owner info, plan, counts, ANAF token status). However, with no annotations provided, the description carries full burden; it doesn't mention whether this is read-only (implied by 'List'), sort behavior, or response pagination shape, though listing is safely inferable as non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. Front-loaded with the core action, then the authorization gate, then the returned-data value. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward read-only listing tool with full schema coverage, the description covers the essentials: scope, authorization, pagination/filtering, and returned fields. Minor gaps exist (response format/sort order) but no output schema exists, and for an admin list tool this is acceptably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters already have descriptions. The tool description adds the search scope ('name or owner name/email') and the specific data fields returned, which enriches meaning beyond the raw schema. This is a solid baseline case where the schema carries most weight and the description complements it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb+resource ('List all organizations on the platform') with pagination and filtering, and clearly targets SUPER_ADMIN only. It distinguishes itself from related admin tools (admin_stats, admin_users) by listing the specific data fields returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly states SUPER_ADMIN-only access constraint, which is important usage guidance. However, it doesn't explicitly contrast with sibling admin tools like admin_stats or admin_users, nor state when NOT to use it. The role restriction is a clear boundary condition but no alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the destructive consequence (revokes synchronization access for the CIF) and names the source of the token ID. It conveys that this is an irreversible/impactful action by describing the effect on e-Factura sync. This is good disclosure for a single-param delete operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. Each sentence earns its place: the first states the action and consequence, the second clarifies the parameter origin. Excellent front-loading and brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-param delete tool with full schema coverage and no output schema, the description is appropriately complete. It explains the impact (revokes sync access), the consequence (irreversible), and where the ID comes from. Multiple related anaf_* siblings exist, but the destructive nature of this operation is sufficiently conveyed. No significant gaps for a tool of this simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and there is one parameter, which is fully described in the schema itself ('The ANAF token ID to delete'). The description restates the schema's parameter info ('token ID is an integer obtained from anaf_tokens'), which adds modest value by clarifying the source. With full schema coverage and no additional complexity, a baseline 3 is appropriate — the description doesn't need to add much.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Delete), resource (ANAF OAuth token), and consequence (revokes e-Factura synchronization access for the associated CIF). It also specifies that the token ID is an integer from anaf_tokens, which distinguishes it from related tools like anaf_create_token_link and anaf_sync_trigger. This is a specific, actionable purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the deletion accomplishes (revokes synchronization access), which implies when to use it (when you need to revoke access). However, it does not explicitly state when NOT to use it versus alternatives, nor does it mention prerequisites like the token being obtainable from anaf_tokens (though it does reference where the token comes from). No alternative filtering or exclusion guidance is provided despite the many anaf_* sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With zero annotations provided, the description carries the full burden of behavioral disclosure. It does describe what is returned (token ID, CIF, expiry, validity status), which is useful. However, it does not disclose whether this is a read-only operation, any permission requirements, rate limits, or what happens when no tokens exist. For a list operation the burden is lighter, but no annotation coverage means the description should say more.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste. First sentence states the verb and scope, second sentence adds the per-CIF context and return fields. Every word earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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, the description is largely complete. It states what it lists, the association to companies/CIFs, and the return fields. There's no output schema, but the description adequately covers return values. Missing minor details like pagination or error cases, but these are less critical for a list endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so the schema covers 100% and there's nothing to document. The description adds meaning about the output fields (token ID, CIF, expiry, validity status) which is helpful context beyond the empty schema. A baseline of 4 is appropriate for a zero-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists ANAF OAuth tokens for the authenticated user, with a specific verb ('List') and resource ('ANAF OAuth tokens'). It distinguishes from related tools like anaf_create_token_link and anaf_delete_token by focusing on listing rather than creating/deleting. The CIF per-company context is a useful differentiating detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes context (tokens associated with authenticated user, each tied to a specific company CIF for e-Factura). However, it does not explicitly state when to use this vs alternatives like anaf_sync_status or anaf_create_token_link, nor any exclusions. The 'authenticated user' qualifier implies auth is needed but doesn't state a prerequisite explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses that processing is asynchronous and returns a job ID, which is valuable. It also notes what's included (all company data plus optional files). However, it doesn't disclose whether this mutates state beyond creating a job, whether it can be called repeatedly (duplicate backups), cost implications, or what the backup download/restore flow entails. For a create-type tool with zero annotations, more disclosure of side effects would help.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero filler. It front-loads the core purpose, then covers scope, optional behavior, and return value efficiently. Every sentence adds information relevant to decision-making and invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create-tool with 2 documented params and no output schema, the description is reasonably complete: it covers what happens (async job), what's included, the optional flag, and the return value. It doesn't explain how to retrieve the backup or interpret the job ID beyond 'check status,' but sibling backup_status and backup_download tools exist to cover those. Given the tool's simplicity and full schema coverage, this is solid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are documented in the schema. The description confirms companyId defaults to active company and includeFiles defaults to true, slightly reinforcing the schema. However, it adds minimal value beyond the schema's parameter descriptions. Baseline 3 is appropriate given full schema coverage, though the description does reinforce the default behaviors which adds a small amount of semantic clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb+resource: 'Create a new backup job for the active company.' It specifies scope (all company data: invoices, clients, products, settings) and distinguishes from sibling tools like backup_status, backup_download, backup_restore which handle other backup lifecycle stages. This effectively disambiguates it from the 8 backup-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it creates a job and returns a job ID to check status, implying the agent should use backup_status to track progress. It mentions the optional includeFiles flag. However, it doesn't explicitly note when to use another tool instead or any prerequisites (e.g., active company must exist). The asynchronous nature is disclosed, which guides the agent on follow-up actions, but no explicit exclusions or alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses key behaviors: direction is auto-set for deposits/withdrawals, direction required for kind=other, movementDate constraint against account opening date. It doesn't state side effects like whether this affects the cash register balance or requires permissions, but the disclosed field-level behavior is meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact three-part statement covering purpose, direction logic, and the date constraint in two sentences. It's front-loaded with the core purpose and adds only essential behavioral nuance. Slightly more could be said but nothing is wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with 7 parameters (100% schema-covered), no output schema, and no annotations, the description covers the key business rules (direction auto-derivation, date constraint) that the schema alone won't reveal. It could benefit from noting the absence of a cash account selection parameter (which appears omitted from the schema) and whether the ledger is updated automatically, but overall it's adequate for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 value beyond the schema by explaining the business logic: how direction is auto-derived for deposit/withdrawal, the relationship between kind and direction, and the movementDate constraint. This exceeds the baseline by clarifying inter-parameter semantics that the schema alone shows as separate enum fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource ('Record a manual cash movement') with specific kinds (deposit, withdrawal, miscellaneous). It clearly distinguishes itself from sibling tools like cash_register_balance, cash_register_ledger, and cash_register_movements_list/update/delete by focusing on the 'create' action, though the tool name already conveys this.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use it (recording manual cash movements) and explains the direction auto-setting logic for deposits/withdrawals vs other. It doesn't explicitly name alternatives, but the create/update/list/delete sibling pattern makes usage obvious. A 5 would require explicit exclusions like 'use update for existing movements'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that 'Results are cached for 5 minutes,' which is a useful behavioral trait. However, it doesn't describe return format, pagination/limit behavior, or error handling for invalid county codes, leaving some gaps for a lookup tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, purposeful sentences with zero filler. Each sentence adds value: what it does, when to use it, and a behavioral note about caching. Perfectly front-loaded with the core purpose stated immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter lookup tool with a clear read-only purpose, the description is complete enough. It identifies the use case, documents the cache behavior, and the schema covers both parameters. No output schema means the agent gets no return-format detail, but for a city-list lookup that's a minor gap. Slightly more on county code format validation would improve it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (q as optional search filter, county as code or name with examples). The description adds context about the optional filtering behavior and caches the data, but doesn't materially extend beyond the schema's existing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Get a list of cities for a given Romanian county'. It specifies the geographic scope (Romanian counties) and the optional filter behavior. It's well-differentiated from its sibling company_registry_search, which handles broader company lookups, while this tool is specifically for city lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States a concrete use case: 'Useful for address auto-complete when creating clients or companies.' It clearly implies when to invoke this tool. It doesn't explicitly name an alternative tool or exclusion cases, but the use case framing provides adequate contextual guidance given the sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the burden. It discloses the key mutation behavior: creates one invoice combining all lines and marks all delivery notes as invoiced. It doesn't describe what happens to the delivery notes beyond marking them invoiced, or what the invoice response contains, but the core side effects are stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero waste. Front-loaded with the primary action, then constraints, then effect. Every sentence carries distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the operation, constraints, and side effects well. It doesn't explain error behavior when preconditions fail (e.g., mismatched clients), but with heavy schema coverage and no output schema, it's reasonably complete for a bulk operation. No explicit return-value info is needed since there's no output schema, though the implications for unsupported combinations could add value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions for both parameters (ids and companyId). The description adds the constraint context (same client, same currency) that affects which ids are valid, which is useful, but the schema already documents parameter meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Convert multiple issued delivery notes into a single invoice.' The scope is well-defined (bulk conversion, single combined invoice) and it clearly distinguishes itself from siblings like delivery_notes_convert (which presumably handles one) and proforma_invoices_convert.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the preconditions explicitly: all delivery notes must be issued, have the same client, and use the same currency. That's strong context for when to use this tool. It doesn't name an alternative explicitly, but the bulk-vs-single distinction with delivery_notes_convert is implied clearly enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full behavioral disclosure burden. It effectively states the key consequence: 'Once issued, the delivery note becomes read-only' — a critical side effect. It also describes the state transition from draft to issued. This goes beyond the bare minimum by warning the agent about the permanent read-only consequence, which is significant behavioral information for a mutation tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the action and trigger condition, then reveal the key consequence. Zero wasted words, each sentence carries essential information. Well structured with the purpose first and side effect second.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and no annotations, the description covers the essential elements: the action, the trigger condition, the state transition, and the read-only side effect. The 2-parameter schema with 100% coverage means parameter documentation is already handled. The description is complete for the complexity level of this tool; it could theoretically mention prerequisites or reversibility, but the 'read-only once issued' note implicitly covers irreversibility.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — both uuid and companyId have descriptions in the schema. The description adds little beyond what the schema provides, mentioning nothing about the companyId override behavior. The uuid parameter is adequately documented in the schema, so baseline 3 is appropriate since the description doesn't need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Mark a delivery note as issued'), the trigger condition ('when the physical delivery of goods or completion of services occurs'), and the state transition ('Transitions status from draft to issued'). It distinguishes itself from sibling tools like delivery_notes_create, delivery_notes_update, delivery_notes_cancel, and delivery_notes_storno by focusing on the specific issue action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use it (when physical delivery occurs), but does not explicitly state when NOT to use it or mention alternatives. It does not explain the relationship to delivery_notes_storno or delivery_notes_cancel, which represent alternative lifecycle states. The trigger condition is useful context but exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of disclosure. It discloses that the output is base64-encoded PDF binary data and that there's a status prerequisite. However, it doesn't mention potential error conditions (e.g., what happens if the delivery note is in another status) or response size implications of base64 encoding. This is reasonable but not comprehensive for an unannotated read/download tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero waste. Front-loaded with the core purpose (download PDF), then return format, then status prerequisite, then optional behaviors. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a download tool with 100% schema coverage and a clear return type stated, the description covers the essential usage points: what it does, the status constraint, and the optional flags. It could mention padding/error behavior for non-eligible statuses, but for a straightforward PDF retrieval tool, this is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all 4 parameters well. The description adds modest value by explaining the status constraint on the uuid and the hideVAT/hidePrices purpose (simplified delivery documents), which complements the schema. This aligns with the baseline 3 for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool downloads a PDF for a delivery note and specifies the base64-encoded return format. It names the specific resource (delivery note) and verb (download/returns PDF), clearly distinguishing it from siblings like delivery_notes_get and delivery_notes_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies that the delivery note must be in 'issued or converted' status, which is a clear prerequisite condition for use. It also explains the optional hideVAT/hidePrices behavior, giving context for when those options apply, though it doesn't explicitly mention alternatives or 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral disclosure burden. It states the state transition effect (cancelled → draft) and that re-issuing is enabled afterward. However, it doesn't disclose whether related records (e.g., linked invoices, stock movements) are affected or if there are any side effects beyond the status change.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, three sentences total, with no filler or redundant information. The first sentence states the primary action, the second adds the precondition, and the third explains the business consequence. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple state-transition tool with 2 well-documented parameters and no output schema needed, the description covers the essential behavior. The precondition and post-condition are stated. A small gap exists around side effects on linked documents, but the tool is simple enough that this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (uuid and companyId) are documented in the schema with their descriptions already matching the parameter names. The description adds the condition that only cancelled notes qualify, which gives context to the uuid parameter, but the schema already defines both parameters adequately. Baseline 3 is appropriate given full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (restore), the resource (delivery note), and the target state (back to draft status). It also distinguishes this operation by specifying it only applies to cancelled delivery notes, differentiating it from sibling tools like delivery_notes_create, delivery_notes_cancel, and delivery_notes_storno.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the precondition ('Only cancelled delivery notes can be restored') and the consequence ('reverses the cancellation and allows the delivery note to be re-issued'). It doesn't explicitly name alternative tools for different states, but the cancel/issue sibling tools make the context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries disclosure burden. It reveals the tool returns both parsed details and raw ANAF response data, and includes related invoice information when available. This is helpful behavioral context, though it doesn't disclose details like error behavior for unknown UUIDs, auth requirements, or rate limiting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with zero waste. The first sentence states the core purpose, the second adds value about included related data, and the third gives a concrete use case. Perfectly front-loaded and appropriately sized for a single-parameter retrieval tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter getter with 100% schema coverage and no output schema, the description adequately explains what data is returned (parsed details, raw ANAF data, related invoice info) and a use case. No output schema means it can't lean on that for completeness, but the description's disclosure of return content compensates well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — the single 'uuid' parameter is fully documented in the schema as 'UUID of the e-Factura message to retrieve.' The description adds no additional meaning about the parameter format or constraints beyond the schema, so baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full details of a specific e-Factura message including parsed details and raw ANAF response data. It distinguishes itself from the sibling efactura_messages_list (which lists messages) by being the detail-retrieval counterpart. The verb+resource+scope pattern is specific and clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes it's 'useful for diagnosing specific invoice upload errors,' giving a clear use case. However, it doesn't explicitly say when NOT to use it or name the alternative (efactura_messages_list); differentiation is implied by the name and the 'full details' framing rather than stated explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It adequately discloses the rounding to 2 decimals, the cross-rate mechanism through RON, and the BNR data source, all of which are meaningful behavioral traits. It does not disclose failure modes or what happens if a currency/date is unsupported, but the core behavior is transparent for a compute-style endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: what the tool does, the cross-rate special case, and the rounding rule. No filler or redundancy. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple static-conversion tool with 100% schema coverage and no output schema, the description is quite complete. It covers operation semantics, rate source, special case handling (cross-rates), and output formatting (rounding). The only minor gap is not describing the response format, but outputSchema doesn't exist and the tool is simple enough that only a mild gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all 4 parameters (to, from, date, amount). The description adds value by explaining the round-to-2-decimals behavior and cross-rate logic, which gives context for how 'amount' is processed. The date parameter semantics ('defaults to latest rates') is handled by the schema description, and the description doesn't add param-specific detail, but the behavioral rounding context compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb+resource: 'Convert an amount between two currencies using current BNR exchange rates.' It clearly explains the cross-rate mechanism for non-RON to non-RON conversions and distinguishes from exchange_rates_list (a sibling that lists rates). The BNR source and rounding behavior are concretely specified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the conversion mechanism and that BNR rates are used, giving clear context for when to use it. However, it doesn't explicitly state when NOT to use it or mention alternatives (e.g., exchange_rates_list for viewing raw rates without conversion), though the purpose does imply it's for converting values.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite having no annotations, the description does meaningful behavioral disclosure: it states that resending does NOT extend the expiration date, which is a critical behavioral trait users must know. It also outlines the correct fallback behavior for expired invitations. This addresses the main side-effect concern (expiration implications) that would otherwise be unknown.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero wasted words. It states the core action, the important behavioral caveat (no expiration extension), and the fallback rule. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with full schema coverage and no output schema, the description covers the key operational aspects: what it does, its limitation regarding expiration, and the correct alternative workflow. It could mention whether there are rate limits or prerequisites (e.g., invitation must not be accepted), but for its simplicity it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the single parameter 'uuid' is fully documented in the schema. The description adds no additional param meaning beyond the schema's 'Invitation UUID to resend', but with full 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it resends an invitation email for a pending invitation, which is a specific verb+resource action. It distinguishes from invitations_create and invitations_delete siblings by the action type, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear guidance on when to use this tool: only for pending invitations. It also gives an important operational instruction - if the invitation has expired, cancel and create a new one instead of using this tool. This implies an exclusion criterion (expired invitations), though it doesn't explicitly name alternatives like invitations_create.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so description carries the burden. It discloses what the tool returns (suggested to/cc/subject/body with substituted variables) which implies it reads template data rather than mutating. It does not disclose whether this counts against rate limits, whether company template config may be required, or edge behaviors. For a read-only suggestion tool this is reasonably transparent but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose first, then the returned fields, then guidance. Zero waste, no redundant phrasing. Excellent structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a straightforward read-only pre-fill tool with 1 required param (uuid). No output schema, but the returned fields are enumerated in the description (to, cc, subject, body). For its simplicity, the description covers the essential behavior. Sibling invoices_email exists and the chain is clear. Could mention that delivery_notes_email_defaults and receipts_email_defaults share the same pattern, but that's not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds context about template-variable substitution but doesn't elaborate on parameter semantics beyond that. The language param enum (ro/en) and companyId override are documented in schema. Description adds marginal value: it clarifies output fields but not parameter usage details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description has a specific verb+resource: 'Get pre-filled email content for an invoice based on the company email template'. It clearly states what is returned (to, cc, subject, body with template variables substituted) and differentiates from the sibling invoices_email (which actually sends).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States clear usage: 'Use this to populate the email form before calling invoices_email.' This gives a when-to-use and a clear chain (populate form, then send). It doesn't explicitly state when NOT to use it or name alternatives, but the purpose is distinct enough from siblings (email_defaults vs email) that guidance is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It discloses what data is returned (delivery status, open/click tracking, bounce info, who sent each email), which is good behavioral context. However, it doesn't disclose pagination/limits for 'complete history', whether companyId scoping affects results, or what happens for invoices with no sent emails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose ('Get the complete history of emails sent for an invoice'), followed by the data scope and use case. Zero filler or redundant content. Very efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only history retrieval tool with 2 well-documented parameters and no output schema, the description adequately communicates the tool's purpose and use case. The data points returned are enumerated, which helps set expectations. Minor gaps around pagination and edge cases (no emails sent) prevent a 5, but the tool's simplicity doesn't demand much more.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both uuid and companyId have descriptions in the schema). The description adds context that the tool returns delivery tracking data but doesn't add detail on either parameter beyond schema. Baseline of 3 applies since schema already documents parameters well; description adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb+resource: 'Get the complete history of emails sent for an invoice'. It lists specific content delivered (delivery status, open/click tracking, bounce info, who sent each email) and its use case (audit trails, verifying client receipt). Distinguished from siblings like invoices_email (which sends) and invoices_email_defaults by focusing on history/audit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames the tool as a read-only audit/history tool, and states it's 'Useful for audit trails and verifying client received the invoice'. It doesn't explicitly name alternatives or state when-not-to-use, but the purpose (retrieving history vs sending emails) is clear enough in context of sibling tools like invoices_email. A small gap: no mention of gating requirements like whether the invoice must be sent first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. The description discloses the return type (XML text content) and the export format, which is useful. However, it doesn't disclose whether this is a safe read-only operation, whether it triggers side effects, or whether the export is large/paginated. The return format disclosure is valuable but the safety profile is unaddressed. Since this appears to be an export operation (read-like), basic behavioral transparency about it being non-destructive would have added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, dense with information: purpose, target format, sibling relationship, and return type. Every sentence adds value with zero filler. Well front-loaded with the core purpose first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 9 parameters but all are documented at 100% schema coverage with enums. No output schema exists, but the description explicitly states the return format (XML text content). For an export-with-filters tool, the description plus rich schema adequately covers usage. The main gap is that it doesn't note whether the export is synchronous/large or if there are limits, but this is minor for this tool type.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 9 parameters with clear descriptions and enums. The description correctly notes these are the same filters as invoices_export_csv, which provides cross-tool context. However, it adds no parameter-level detail beyond the schema—no format, defaults, or behavioral notes for specific filters. Baseline 3 is appropriate when schema carries the full load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (export), resource (invoices), format (Saga XML), and purpose (accounting software integration like Saga C). It explicitly declares 'Accepts the same filters as invoices_export_csv' and 'Returns XML text content', which fully distinguishes this tool from the related invoices_export_csv and invoices_export_efactura_zip sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this is for accounting software integration and accepts the same filters as invoices_export_csv. It doesn't explicitly state when NOT to use this tool versus alternatives (e.g., when to use efactura_zip or receipts_saga_xml instead), but the format-specific purpose is clear enough that an agent understands the use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. The tool is a read operation (listing members), which is clear from the verb. The description discloses the access restriction (admins/owners only) and indicates what fields are returned. Since this is a read-only listing tool, the behavioral surface is minimal and well-covered, though it doesn't explicitly mention response format or ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. The first sentence states exactly what is returned, the second adds the single most important constraint (who can call it). Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only list tool with clear purpose and access requirements, the description is complete. It could theoretically mention pagination or filtering, but with no parameters available, the description covers the essential information an agent needs: what it returns and who can invoke it. A minor enhancement would be noting any pagination behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so there are no parameter semantics to clarify. The schema is trivial (empty properties object) with 100% coverage by default since there are no parameters. A baseline of 4 is appropriate for a zero-parameter tool where no compensation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List'), resource ('all members of the organization'), and the specific data returned (roles, active status, allowed company access). It distinguishes well from sibling member tools like members_update/members_delete which mutate, and members_permissions_reference which references permissions. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states a permission prerequisite ('Only organization admins and owners can list members'), which gives clear context about who can invoke it. However, it does not explicitly discuss when one would choose this over interactions list/invitations_list, nor provide explicit exclusions or alternative recommendations. The access control note is useful context but not a full usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but this is a read/reference tool (get permissions reference), so the safety profile is inherently low-risk. The description explains what content is returned (all permissions grouped by category, role default permissions for each role) and enumerates the roles (owner, admin, accountant, employee), which adds useful behavioral context beyond a bare 'Get permissions reference' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, completely free of fluff. The first sentence states the purpose and the second provides concrete usage context. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless reference tool with no output schema, the description fully specifies what it returns (categorized permissions and role defaults) and when to use it (before setting custom permissions on a member). Given the tool's low complexity - zero parameters, read-only semantics - this is a complete and self-sufficient description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and the schema coverage is 100%. There are no parameters to document, so the baseline of 4 applies. The description covers what output the agent can expect, which is the relevant semantic content for a parameterless reference tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets 'the permissions reference' with all permissions grouped by category and role default permissions. It identifies the specific verb (get) and resource (permissions reference), and distinguishes its purpose from the member_update/member_delete sibling tools by framing it as a lookup/reference tool rather than a mutation tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states it is 'Useful for understanding which permissions exist before setting custom permissions on a member.' This provides clear when-to-use guidance tied to setting custom permissions. It doesn't explicitly name sibling alternatives or exclusions, but the reference-vs-action contrast with members_update is implied and the keyword is specific enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The 'Get' verb and 'Returns per-event settings' phrasing clearly imply a read-only operation with no side effects, which is useful. However, it doesn't mention whether the return includes defaults for unset preferences, pagination, or response shape, and with no annotations the description could add more safety context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with zero wasted words. The first establishes the verb and resource, the second enumerates the return scope. Perfectly sized for a parameterless getter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless read operation with the channels enumerated in the description, the tool is adequately documented. The lack of an output schema means the return-shape detail ('per-event settings for email, in-app, push, and WhatsApp') in the description compensates well. Revealing whether defaults are included would push this higher, but completeness is solid for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters and schema coverage is 100%, so all parameters are trivially documented. The description adds value by specifying exactly what will be returned (per-event settings for email, in-app, push, and WhatsApp channels), which is semantically meaningful despite the absence of parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get'), the resource ('the authenticated user's notification preferences'), and the scope ('for all event types'). It distinguishes this GET tool from its sibling 'notification_preferences_update', and specifies the channels covered (email, in-app, push, WhatsApp), making the purpose explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a read operation to retrieve current settings, which provides reasonable context. However, it doesn't explicitly state when to use this tool vs the update sibling, and no return format or use context (e.g., 'call this before updating to understand current state') is given. The 'all event types' scope is helpful but provides no exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries full burden. It discloses idempotency (no error on already-read), the unread-count side effect, and the single required parameter. This is meaningful behavioral disclosure for a mutation, though it doesn't mention reversibility (unmark read) — reasonably complete for a simple state change.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, zero fluff. First sentence states the purpose, second reveals the behavioral key facts (idempotency and unread count impact). Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with 100% schema coverage and no output schema, the description is essentially complete. The only gap is not specifying the return value shape (e.g., updated notification, success status), but for a mark-read operation with full schema documentation, the current disclosure is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — the schema already documents 'id' as the 'Notification UUID to mark as read'. The description adds 'specific notification' but doesn't go beyond the schema's parameter semantics. Baseline 3 applies since the schema does the heavy lifting adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource ('Mark a specific notification as read'), explicitly identifies the single parameter, and distinguishes from siblings (notifications_list, notifications_unread_count, notifications_read_all). The 'specific notification' wording clearly separates this from bulk operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use guidance or alternatives named. The mention of idempotency and unread count decrement gives some context about behavior, but doesn't tell the agent when to choose this over notifications_read_all or when marking read is appropriate versus leaving unread.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral disclosure burden. It handles this well: it explicitly states the state transition, that issuance makes the receipt read-only, and that fiscal data becomes locked. This directly discloses mutations and consequential irreversible effects. It could add info about required permissions or errors on non-draft receipts, but the core behavioral contract is well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero filler. Each sentence earns its place: purpose, state transition, and irreversible consequence. Front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-param, no-output-schema tool, the description covers the transition semantics and the irreversible consequences. The absence of an output schema means the return value isn't specified by structure, but for a state-transition tool the critical info (what happens, what locks) is present. It doesn't address error behavior on already-issued or draft-invalid receipts, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema documents both params ('UUID of the receipt to mark as issued' and 'Company UUID (overrides configured default)'). The description adds no additional param-level meaning beyond what the schema provides, so the baseline 3 applies. It doesn't elaborate on the companyId override semantics, but the schema already covers it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource+action: 'Mark a receipt as issued at the point of sale.' It clearly distinguishes from siblings like receipts_get, receipts_update, receipts_delete, receipts_cancel, receipts_refund, receipts_convert_to_invoice by naming the specific state transition (draft→issued).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description communicates the context (point of sale issuance, draft-to-issued transition) but does not explicitly state when not to use it or name alternative tools. With siblings like receipts_cancel, receipts_refund, and invoices_issue existing, explicit exclusions would help, but the draft-to-issued framing implies the precondition clearly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does a good job: it discloses asynchronous processing (fire-and-forget), the 100-per-batch limit, and the important detail that data always goes to api.storno.ro regardless of base URL configuration. It does not describe response/return behavior (no output schema), which is a minor gap for a write-type operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences covering purpose, behavior, limit, and a notable routing caveat. Zero wasted words; every sentence earns its place. The critical override detail (api.storno.ro regardless of base URL) is front-loaded near the end but highly value-bearing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 required param, no nested objects, no output schema), the description covers the key operational facts: rate limit, async behavior, and routing override. It could add return-value/error handling info, but for a telemetry send operation with 100% schema coverage, the completeness is solid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters (events, platform, companyId). The description adds a couple of operational details (100 max events, async processing) but does not add much beyond what the schema already explains for each parameter. Baseline 3 is appropriate given the full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sends a batch of telemetry events for the current user and company, with a specific verb ('send') and resource ('batch of telemetry events'). It distinguishes itself well from sibling tools since no other telemetry tools exist among the siblings, though it doesn't explicitly contrast with any alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: telemetry is for the current user/company, processed asynchronously, max 100 events per batch. It notes a notable behavioral quirk (always sent to api.storno.ro regardless of configured base URL). It doesn't explicitly state when NOT to use it or name alternatives, but this tool has no obvious sibling competition, so the guidance is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of behavioral disclosure. It discloses a key side-effect: changing the rate percentage does not retroactively affect existing invoices, and that setting isDefault demotes any existing default (also documented in schema). It doesn't mention permission requirements or reversibility, but the description adds meaningfully useful behavioral context beyond what's implied by 'update'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, information-dense sentences with no filler. Front-loaded with the core purpose, followed by the key caveat about non-retroactivity, then the field scope and the required-field constraint. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description covers the core behavioral nuances well: non-retroactive rate changes, the updatable field set, and the 'at least one field' constraint. It could mention whether the operation is reversible or idempotent, and the companyId override nuance is only in the schema, not the description. For a simple update tool with a clean schema, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. All seven parameters have descriptions in the schema (VAT percentage, UUID to update, display label, display order, company override, default demotion, category code enum values). The description adds minor context like 'at least one field must be provided' but does not add significantly beyond the schema's own parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear action ('Update an existing VAT rate') on a specific resource (VAT rate), and explicitly lists the updatable fields (display label, category code, default status, position). It differentiates from create/delete siblings via the word 'existing' and update framing. However, it doesn't explicitly name sibling tools like vat_rates_create or vat_rates_delete, though the purpose is clear enough by context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on scope: it only updates certain fields and explicitly excludes the rate percentage from being a separately-updated retroactive effect ('changing the rate percentage does not retroactively affect existing invoices'). It states the 'at least one field must be provided' constraint. It doesn't explicitly say 'use this instead of vat_rates_create' but the behavioral distinction is reasonably clear for an update tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses what data the tool returns (request payload, headers with signature, full response), which is useful. It doesn't disclose any authentication requirements, potential data volume/size, or whether headers truly include the signature in all cases, but for a read-only detail retrieval the disclosed behavior is reasonably complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The first sentence enumerates what's returned specifically, and the second gives a crisp usage directive. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only detail-retrieval tool with 100% schema coverage and 2 required params, this is complete. The description effectively communicates what it returns and when to use it. Since there's no output schema, the description's explicit enumeration of returned content (payload, headers, response) compensates well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all 3 parameters (uuid, companyId, deliveryUuid). The description adds that the request payload/headers are returned, which is about the output not parameters. Baseline 3 is appropriate since the schema handles the heavy lifting for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Retrieve') with a clear resource ('complete details of a single webhook delivery attempt') and explicit scope (request payload, headers with signature, full response). It distinguishes itself from siblings like webhooks_deliveries (list) and webhooks_get by targeting a single delivery attempt's detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for use ('Use this to debug failed deliveries'), which gives the agent a concrete trigger scenario. However, it doesn't explicitly mention alternatives or when NOT to use it, though the sibling set (webhooks_deliveries for listing) makes the differentiation fairly obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It discloses the mutation semantics (partial update, replacement of events list, HTTPS constraint) which is helpful. However, it doesn't mention whether changes are reversible, auth requirements, or delivery impact on in-flight requests. Decent but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, each earning its place: states partial-update behavior, discloses the events-replacement gotcha with clear guidance, and flags the HTTPS constraint. Zero waste, well front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward CRUD-update tool with 100% schema coverage and no output schema, the description covers the key behavioral semantics (partial update, events replacement, HTTPS). Could add auth/permission expectations, but the essentials are present. Complete enough for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all 6 parameters thoroughly (including the non-additive events semantics and '*' wildcard). The description adds the 'send complete set' emphasis which reinforces the events param, but otherwise does not add meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource ('Partially update an existing webhook endpoint') with explicit semantics that it's a partial update. Distinguishes from webhooks_create/webhooks_delete/webhooks_test siblings through the 'existing webhook endpoint' framing and partial-update specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes partial-update behavior and the critical events-replacement caveat ('send the complete desired set each time'). Notes HTTPS requirement. However, it doesn't explicitly say when not to use it or contrast with webhooks_create for new endpoints, though the 'existing' qualifier implies it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It discloses the access requirement (SUPER_ADMIN), the resource type (lifecycle emails), and the available filter categories. However, it doesn't state that this is a read-only operation explicitly, what fields are returned per entry, how pagination behaves in edge cases (e.g., default page size is in schema), or whether results are sorted. For a list/audit tool the access-level disclosure is valuable, but several behavioral details remain unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact—two well-formed sentences that front-load the purpose and permission, then enumerate categories and use cases. The list of categories is slightly long but functionally necessary. It wastes minimal words and each clause adds value. Could trim slightly but remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a filtered list/audit tool with 8 well-documented parameters and no output schema, the description covers purpose, categories, and use cases adequately. The access-level requirement is disclosed, which matters for an admin tool. A note about the return format or sort order would improve completeness, but the description communicates enough for an agent to successfully invoke and interpret the tool in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every one of the 8 parameters already has a description in the schema. The tool description lists the email categories and use cases, which complements the schema by explaining what the category enum maps to (though the actual enum only has 4 status values, not the 6 categories listed). Most parameters are self-explanatory (page, limit, dateTo, dateFrom). The description adds meaningful filter context but doesn't elaborate on parameter formats beyond what the schema provides, matching the baseline 3 for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb+resource ('List lifecycle email log entries') and explicitly states the operation is a read/audit tool scoped to admin. It enumerates all six email categories, which distinguishes it clearly from the mail_config, webhooks_deliveries, and notifications tools. The statement 'SUPER_ADMIN only' adds access-level clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool: 'Use to audit delivery, debug suppressions, or check drip cadence.' This gives concrete usage scenarios that differentiate it from related email/log tools. It also names the access restriction (SUPER_ADMIN) which is an implicit prerequisite. No alternative tools are named, but the use cases are specific enough that an agent can decide appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It clearly states the tool is read-only (retrieval of a log) and specifies the fixed window (last 50 invoices). However, it doesn't disclose the return format/structure, whether results are paginated, or any ordering guarantees beyond 'recent'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tight sentence in active voice that efficiently communicates the purpose, scope, and content of the returned data. Every clause earns its place — no filler, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple, parameterless read tool with no output schema required. The description fully explains what the user gets (log entries with 4 fields each) and the fixed limit (50). There is no complexity that demands additional disclosure, and with no parameters and no annotations needed, the description is complete for its simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter schema for the description to add meaning to. The baseline for 0 parameters is 4, and the description appropriately covers what data the log contains without needing parameter documentation. It correctly describes the fixed nature (always last 50, no filtering options).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Retrieve the recent e-Factura sync activity log') with clear scope ('last 50 synced invoices') and details the content of each entry (invoice ID, company CIF, sync timestamp, status). This clearly distinguishes it from siblings like anaf_sync_trigger and anaf_sync_status, which deal with triggering and status checking rather than log retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for viewing historical sync activity, which is a clear enough context. However, it doesn't explicitly state when to use this vs anaf_sync_status (which likely shows current sync state) or anaf_sync_trigger (which initiates a sync). The distinction is implied by the 'log' framing but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully reveals partial-update semantics (omitted fields keep current value), the currency immutability constraint, and the auto-direction re-application behavior when kind changes. These are genuinely valuable behavioral insights beyond the raw schema. It doesn't mention whether operation is destructive or requires permissions, but the disclosed behaviors are meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, zero filler, front-loaded with the core action. Every sentence carries meaningful behavioral information (field optionality, currency constraint, direction re-application). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update tool with 8 parameters and no output schema, the description covers the key edge cases: partial updates, immutability of currency, and kind/direction interaction. It doesn't explain the return value or what happens to movementDate/amount validation, but for a partial-update tool this is reasonably complete given the schema's own parameter descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 63%, meaning some parameters lack descriptions in the schema. The description compensates with partial-update semantics and the direction/kind interaction rule. It doesn't enumerate every parameter, but the schema already provides descriptions for uuid, companyId, description, documentNumber, and movementDate. The description adds value by explaining omitted-field behavior and the kind/direction coupling.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this updates a manual cash movement with a specific verb ('Update') and resource ('manual cash movement'). It differentiates from siblings via 'manual' (distinguishing from create/list/delete/balance/ledger tools in the same domain). It doesn't fully distinguish from cash_register_movements_create, but the purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear parameter behavior guidance ('All fields optional; omitted fields keep their current value') and important constraints ('Currency cannot be changed', 'Changing kind between deposit/withdrawal re-applies auto-direction'). However, it doesn't explicitly state when to use this vs. create/delete, though the domain siblings make this reasonably inferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the destructive replacement behavior ('Replaces all line items with the provided array') and status limitations, which are the two most important behavioral traits. It does not state whether the update is reversible, whether a version/draft is created, or what response to expect, but given no output schema and no annotations, the disclosed constraints are valuable. Lacks mention of irreversible effects like losing existing line item references.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, zero waste. Front-loads the purpose, then the critical status constraint, then the destructive line-replacement behavior. Every sentence earns its place with meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 42-parameter mutation tool with no annotations and no output schema, the description covers the essential semantics (update, status limits, line replacement) but omits some context: whether the note number/series is immutable after issue, consequences for already-issued notes, and any return value/confirmation. The complexity is high, and richer behavioral context (e.g., e-Transport field validation interplay with replacement) could be stated. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so every parameter is documented in the schema. The description highlights the crucial line-replacement semantic ('Replaces all line items with the provided array'), which is not evident from the schema alone. With full coverage, the baseline is 3 and the added 'replaces' note is useful context but doesn't go beyond the key semantic.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States clear verb+resource ('Update an existing delivery note'), plus a critical behavioral constraint ('Delivery notes in draft or issued status can be updated') and the key replacing semantics ('Replaces all line items with the provided array'). Clearly distinguished from siblings like delivery_notes_create, delivery_notes_delete, delivery_notes_issue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Specifies status prerequisites (draft or issued). Does not explicitly contrast with delivery_notes_create for creating new notes vs updating existing, nor state when NOT to use this (e.g., issued notes requiring storno instead). The status constraint provides clear context but no explicit exclusions or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states this is a read-only listing operation (safe, non-destructive), and informs the agent about return contents (identifiers, labels, country codes). The explicit enumeration of providers adds useful predictability. It doesn't describe pagination or response format, but as a zero-parameter enumeration endpoint with no output schema, the disclosure is reasonably complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and highly efficient: the first sentence states purpose and return content, the second enumerates the actual provider values. No wasted words. It could arguably be more concise, but the provider list is genuinely useful, actionable information rather than fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only listing tool with no output schema, the description is nearly complete. It tells the agent what comes back (identifiers, labels, country codes) and enumerates the exact set of providers. The absence of an output schema is partly compensated by the provider enumeration. The only minor gap is not stating whether additional providers can be added or whether the list is cached/static.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is 100% (trivially, since there are no parameters to document). The baseline for 0 params is 4 per the rubric. The description does not need to explain parameters since none exist, and it appropriately avoids padding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('all available e-invoicing providers'). It explicitly states what is returned (identifiers, labels, country codes) and enumerates the actual provider values, distinguishing it clearly from sibling tools. The tool is well-differentiated from related tools like einvoice_submit, einvoice_config_list, and borderou_providers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a discovery/enumeration tool used to know available providers, which is reasonably clear context. However, it doesn't explicitly state when to use this vs alternatives (e.g., einvoice_config_list, borderou_providers), nor does it mention that this is the prerequisite for configuring submissions. No explicit when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses access restrictions (admin/owner only) and filters (pending only), which is useful and accurate. However, it does not describe return format, pagination, sorting behavior, or whether pending invitations are limited by time. The description adds moderate value beyond the name but leaves several behavioral questions unanswered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste. The first sentence states the core purpose, the second adds the key filtering detail and authorization requirement. Every clause earns its place; there is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple zero-parameter list tool with no output schema. The description covers the essential filtering logic (pending only) and access control (admin/owner only). For a tool this simple, the description is largely complete; a small gap exists around whether any other implicit filters apply or whether pagination is a concern, but for a zero-parameter listing of pending invitations the provided information is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so the schema provides no information to add meaning to. With 0 parameters, the baseline is 4 per the rubric, and the description appropriately explains the fixed behavior (lists all pending, not yet accepted invitations). There are no parameter semantics to clarify since there are no parameters, and the description handles this well by clarifying the filtering behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb+resource: 'List all pending invitations for the organization.' It precisely defines scope (pending, not yet accepted invitations) and distinguishes from sibling tools like invitations_create, invitations_delete, and invitations_resend. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about what is returned (only not-yet-accepted invitations) and who can use it (org admins and owners). However, it does not explicitly mention when to use it versus alternatives, nor does it note that this is a read/query operation distinct from invitations_create/delete/resend. The when-not guidance 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral burden. It explicitly discloses that the action is irreversible, returns a count of deleted invoices and per-item errors, and only allows draft status. This covers the key behavioral traits (destructive, conditions, return format) well. It could mention partial-success semantics more explicitly but the per-item errors mention implies it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all informative, front-loaded with the core purpose. No filler. Could perhaps structure the return-value sentence more clearly, but overall tight and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk-delete mutation tool with no annotations and no output schema, the description covers the essential points: eligibility condition (draft only), irreversibility, and return format (count + per-item errors). It effectively signals partial-failure handling. Given the tool's moderate complexity, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — both ids and companyId have descriptions in the schema. The description adds the return-format context (count + per-item errors) and the draft eligibility, but these relate more to behavior than parameters. Schema already explains eligibility for ids and companyId override. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete multiple draft invoices in batch' — a specific verb (delete), specific resource (invoices), scope (multiple/draft), and batch mode. It distinguishes from siblings like invoices_delete (single) and invoices_bulk_cancel (cancel, not delete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the eligibility constraint ('Only invoices with status draft can be deleted') which provides clear context on when this tool can be used. However, it doesn't explicitly contrast with alternatives like invoices_bulk_cancel, invoices_bulk_storno, or the single invoices_delete, nor does it say when NOT to use it — but the draft-only constraint effectively scopes applicability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the disclosure burden. It states the invoice starts in 'draft' status and can be edited until issued, which is good behavioral context. However, it doesn't disclose the idempotencyKey behavior, collect (immediate payment) side-effects, or what the response/return value contains. The description also doesn't mention VAT calculation behavior, penalty handling, or UBL extensions even though these significantly affect behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, tightly packed with the most essential information: required line items, client identification requirement, and draft-to-issue workflow. It's front-loaded with the primary action. It could mention additional critical requirements but doesn't waste words on trivial content. Slightly more substance than the minimum needed, but still concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 50-parameter tool with two required params and rich nested UBL extension structures, the description covers the essential creation semantics (draft status, editability, requirement constraints, issue follow-up). The schema handles parameter detail comprehensively. The main gap is no mention of return value/created invoice response, no idempotency guidance, and no note about validation behavior. Since output schema is absent, some return-value context would help, but overall it's reasonably complete given the schema richness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 50 parameters have descriptions within the schema itself. The schema is extremely detailed with descriptions for each parameter including examples, enums, and nested structures. The tool description itself adds only the clientId vs receiverName/receiverCif constraint, which is also largely covered in the schema. Baseline of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (create), resource (draft invoice), and key preconditions (requires line item and clientId or receiverName/receiverCif). It also distinguishes from the sibling tool invoices_issue by clarifying this creates a draft, while issue finalizes. This differentiates it from proforma_invoices_create and delivery_notes_create among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states required preconditions (at least one line item, either clientId or receiverName/receiverCif) and points to invoices_issue as the follow-up step for finalization and XML/PDF generation. It also clarifies the draft status behavior, giving clear when-to-use guidance versus the issue tool. However, it doesn't contrast with proforma_invoices_create, which could be a near-alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the load for behavior disclosure. It does well to warn about the destructive lines-array replacement behavior, which is a subtle and potentially data-lossy trait. However, it does not disclose the return value, whether partial updates are allowed (beyond lines), or any permission/auth requirements. The key destructive behavior is the most important disclosure and is present, so a 3 is fair.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no waste. The critical facts (draft-only, lines replacement, cancel alternative) are front-loaded and each sentence earns its place. Could arguably be slightly more structured, but it is appropriately compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 49-parameter tool with nested UBL extensions, the description covers the two most operationally critical behaviors: the draft-only restriction and the destructive lines replacement. Since there's no output schema, a brief note on the update response would be useful, but the schema richly documents all parameters. The description is sufficient for correct invocation despite the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline starts at 3. The description adds value for the lines parameter with its replacement warning, which is genuinely helpful. However, it doesn't add meaning beyond the schema for the other 48 parameters. Coverage is high so the schema does the heavy lifting; the lines warning justifies maintaining the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (update), the specific resource (existing draft invoice), and includes a critical scope constraint (only draft status). It also distinguishes from the sibling tool invoices_cancel by explicitly naming it as the alternative for issued invoices, which differentiates it well from the many invoice-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage conditions: only draft-status invoices can be updated, and once issued, invoices_cancel should be used instead. This gives clear when-to-use and when-not-to-use guidance, plus explicitly names the fallback tool for the excluded case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states the endpoint does NOT require authentication (a key behavioral trait), that the license key itself is the credential, and describes the return payload (plan features, org name, billing period end, trial info). It doesn't describe error cases for invalid/expired keys or rate limiting, but the core behavioral traits are well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no waste. The most important facts are front-loaded: purpose, auth requirement, return payload, and call cadence. It's slightly dense but every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a validation tool with 3 well-documented parameters and no output schema, the description covers the essential context: purpose, auth model, return data, and call frequency. It doesn't describe error handling or what happens with invalid/expired keys, which would be valuable for this type of tool, but overall it's quite complete given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all three parameters (licenseKey, instanceUrl, instanceName) with their purposes. The description adds context about the licenseKey being 'the credential' and that instanceUrl/instanceName are 'stored for identification,' which maps to schema semantics. The description doesn't elaborate on formats beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Validate a self-hosted license key') and clearly states what's returned: plan, features, subscription details, organization name, billing period end, and trial info. It distinguishes itself from sibling licensing tools (licensing_create_key, licensing_list_keys, licensing_revoke_key) by focusing on validation/retrieval rather than management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states when to use this tool: 'Used by self-hosted instances every 24 hours.' It also clarifies an important exclusion context by stating this endpoint does NOT require authentication since the license key is the credential. While it doesn't explicitly name alternative tools, the 'every 24 hours' cadence plus the validation focus provides clear usage context among the licensing siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses important behaviors: it mutates the invoice (amountPaid, balance), auto-transitions status, supports partial payments. This is good coverage for a create-type tool. Could add error conditions (overpayment) or reversibility, but the core side effects are well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each carrying real information: purpose, side effects, capability. No filler or redundant restating of the schema. Efficient and front-loaded with the verb and object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with 8 params fully described in schema and no output schema, the description covers purpose, mutation effects, and the partial-payment capability. It could mention what happens on overpayment or partial-vs-full distinction more explicitly, but overall it is reasonably complete for the stated complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 8 parameters are individually documented in the schema. The description adds context about partial-payment support and that paymentMethod defaults to bank_transfer, partially echoing the schema. Baseline 3 is appropriate since the schema does the heavy lifting and the description doesn't add much beyond it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool records a payment received for an invoice, and goes further to explain side effects: updates amountPaid and balance, and changes invoice status to partially_paid or paid. Distinguishes from siblings like payments_delete and invoices_bulk_mark_paid.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes when to use (recording payments on invoices) and the behavior around partial payments and status transitions. Does not mention alternatives like invoices_bulk_mark_paid or payments_delete in explicit comparison terms, but the create-scoped context is fairly clear given the rich payment domain.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral disclosure burden. It explicitly warns that products cannot be manually created or edited and are auto-extracted from invoice line items during ANAF sync - important behavioral context. It notes the company scoping behavior (active company). It doesn't state pagination limits, but those are in the schema. Good proactive disclosure of the immutable nature of products.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences - the first states the core purpose and key constraint (sync-only, not manually editable), and the second covers filtering and search capabilities. No wasted words. It could be slightly more front-loaded about the filtering aspect, but overall it's compact and functional.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation with 100% schema coverage and no output schema, the description provides sufficient context: company scoping, immutable nature, filtering options, and search capabilities. It doesn't document pagination behavior or max limits beyond schema, but the schema handles those. The description is complete enough for an agent to understand what this tool does and its constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 5 parameters are already documented in the schema. The description adds marginal value by explaining the 'active company' scoping and mentioning the search dimensions (name, code, description) which aligns with the schema. This meets the baseline 3 but doesn't exceed it meaningfully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists products for the active company, with a specific verb+resource. It also distinguishes this tool by noting products are sync-only and cannot be manually created, which separates it from products_update and products_get in the context of a read/list operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool - for listing products with filtering by active status and searching by name, code, or description. It doesn't explicitly mention alternatives or when NOT to use it, but the read-only nature distinguishes it from products_update. The 'active company' scoping gives useful selection context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explicitly discloses the critical side effect: files already stored externally will no longer be accessible, AND clarifies an important boundary: it does NOT delete the files from the external bucket. This is exemplary behavioral disclosure for a destructive operation with no annotation safety hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. Every word earns its place: the first sentence states the action and primary consequence, the second clarifies an important non-effect. Exceptionally efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter destructive operation with no output schema, the description is nearly complete. It covers the action, the main side effect, and the key boundary (files not deleted). Minor gap: it doesn't mention whether this can be reversed or if there are prerequisites (e.g., must configure a new provider first), but given the simplicity of the tool, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and schema description coverage is 100% (vacuously, since there are no properties). Per the rubric, 0 params gets a baseline of 4. The description doesn't need to add parameter meaning since there are none to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Delete) and resource (external storage configuration), and distinguishes it from storage_config_get/update/test by focusing on the delete action. It's clear what this tool does, though it could benefit from more explicit distinction from the sibling storage config tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for removing external storage configuration and notes the consequence (files no longer accessible), which gives usage context. However, it doesn't explicitly state when to use this vs storage_config_update or when not to use it, and there's no mention of prerequisites or recovery options beyond the implicit destructive nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals that results are 'typically cached for 5 minutes'—useful for agents deciding whether to call this repeatedly. It also discloses the SUPER_ADMIN permission requirement, warning agents without those credentials against calling. The caching note adds real operational context beyond what the schema or annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. The first sentence lists the data categories, the second states the access restriction and caching behavior. Every element adds real value, and the information is front-loaded with the primary purpose first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read-only aggregation tool with no parameters and no output schema. The description covers what data it returns, its access level, and caching behavior. It is reasonably complete for this level of complexity. It could optionally mention that the output shape is platform-wide (vs per-company), but the absence of an output schema and parameters means the description already covers the essential ground.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema coverage, meaning there is nothing for parameters to add. Per the guidelines, a 0-param tool warrants a baseline 4. The description appropriately focuses on what data the tool returns rather than parameter details, which is the correct prioritization.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: 'Get platform-wide statistics including user counts, organization metrics, company sync status, invoice totals, and system info.' It enumerates the specific data categories, clearly distinguishing it from sibling tools like admin_users and admin_organizations which handle narrower scopes. The 'platform-wide' qualifier and 'SUPER_ADMIN only' restriction make its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes it is 'SUPER_ADMIN only' which provides an access prerequisite—a form of usage guidance. However, it does not explicitly contrast with sibling admin tools (admin_users, admin_organizations, system_health, system_version) or state when one would prefer this aggregated view over specific admin endpoints. The access restriction is helpful but the when-not-to-use guidance 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It clearly describes the return structure (token count, overall validity, per-token details) and implies a safe read operation by nature. It's scoped to the 'authenticated user', clarifying authorization context. While it doesn't add security caveats, the read-only nature is evident and the return details are well-specified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The first sentence states the purpose and scope, the second enumerates the return structure. Every word earns its place with specific detail about what the output contains.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 0-parameter status-check tool with no output schema, the description is quite complete. It describes the full return shape (token count, overall validity, per-token fields). It could note whether this reflects live ANAF validation or cached/local status, and could benefit from stating the authentication requirement more explicitly, but for a parameterless read tool this is near-complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters and 100% schema coverage, so the description isn't needed to explain parameters. With no parameters, the baseline is 4 per the rubric since the description correctly focuses on explaining the return value instead. The description adds meaningful value by enumerating the exact fields returned for each token (CIF, expiry, validity).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Check') with a clear resource ('ANAF integration status'), and specifies exactly what it returns: token count, overall validity, and per-token details including CIF, expiry, and validity. It clearly distinguishes from siblings like anaf_sync_status and anaf_sync_log by focusing on token/status information rather than sync operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly conveys this is a read/inspection tool for checking integration status, which contrasts with siblings like anaf_create_token_link and anaf_delete_token that modify tokens. However, it doesn't explicitly state when to use this vs anaf_sync_status, anaf_sync_log, or anaf_tokens, leaving some ambiguity about which status tool to pick.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses key behavioral traits: the token is single-use and expires after 1 hour, and all existing sessions are revoked on success. This is strong behavioral disclosure for a security-sensitive mutation, covering failure modes (expired/used token) and side effects (session revocation). It doesn't state the success/error response format, but it covers the most critical behavioral implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: purpose, token constraints (single-use + expiry), and side effect (session revocation). Zero verbose filler or redundancy. Exceptionally efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-param auth mutation with 100% schema coverage, the description covers purpose, token lifecycle, and operational side effects. Security-critical details (session revocation, token expiry) are disclosed. There's no output schema to explain return values, and it doesn't specify what error responses look like, but for a password reset the essential behavioral contract is well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema documents both parameters (token and password) with descriptions. The description adds the connection between token and auth_forgot_password, which enriches the token parameter's meaning, but this is marginal value. The password minLength constraint is in the schema. Baseline 3 is appropriate since schema does the heavy lifting and description adds only modest context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb+resource: 'Reset a user password using the token received via email from auth_forgot_password.' It specifies the exact flow (token from email), distinguishes from siblings like auth_forgot_password (which initiates) and auth_login, and provides clear scope of what the operation accomplishes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use: after receiving the token via auth_forgot_password email. It does not explicitly name alternatives or state when NOT to use it, but the context (token received via email from a specific tool) provides clear usage framing. It could add exclusions, but the flow is reasonably well-established.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses key behavioral traits: permanence of deletion, constraints on last/default account, and the data-retention behavior for existing invoices (IBAN retained in stored data). This is strong coverage of side effects and preconditions for a destructive operation, though it doesn't address permission/auth requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no waste. Every sentence earns its place: what it does, what it can't do (with remedy), and the data-retention side effect. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no annotations and no output schema, the description covers the essential risks: permanence, constraints, and downstream data behavior. It could mention auth/permission requirements, but given the simplicity (2 params) this is largely complete for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters described in the schema (uuid and companyId). The description adds minimal semantics beyond the schema—it mentions company context implicitly but doesn't elaborate on companyId override behavior beyond what the schema says. Baseline 3 is appropriate since the schema handles the documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Purpose is clearly stated: 'Permanently delete a bank account.' The verb (delete), resource (bank account), and permanence are all explicit. It distinguishes from siblings by emphasizing 'permanently' and outlining specific constraints (cannot delete last account or default account).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when deletion is NOT possible (last account, default account), with an actionable hint to set another as default first. However, it doesn't explicitly name alternative tools or state when to use it vs. not using it, relying on implied exclusivity from siblings like bank_accounts_update (for setting default).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses the scoping constraint (manual-only movements, excludes receipts/invoice payments), which is useful. However, it does not disclose other behaviors like pagination, result ordering, or whether balances are computed. For a list tool with no annotations, the description covers the core scoping but leaves behavioral details unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no filler. The first sentence states the purpose and scope, the second provides the crucial exclusion and alternative. Every sentence earns its place and the most important differentiator (what it does NOT return) is clearly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-param list tool with 100% schema coverage and no output schema, the description adequately covers what the tool returns and its scoping. The exclusion of receipts/invoice payments is the key differentiator and it's present. It doesn't address pagination or response format, but for a simple list tool with full schema coverage this is a minor gap. Would be a 5 with a small note on result ordering or limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters (to, from, companyId) are documented in the schema. The description adds date-range context ('in a date range') which aligns with from/to params but adds no new semantics beyond what the schema already provides. Baseline 3 for full schema coverage is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('List manual cash movements') and clearly scopes what's included (deposits, withdrawals, miscellaneous) and what's excluded (receipts and invoice payments). It explicitly distinguishes from the sibling cash_register_ledger, naming it as the alternative for the full picture.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent when NOT to use this tool ('Receipts and invoice payments are NOT returned here') and directs to the alternative sibling tool cash_register_ledger for the full picture. This is an explicit exclusion plus named alternative, which is the strongest form of guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It discloses that cached XML/PDF files are invalidated (a side effect on related artifacts), that it rewrites older invoices, and that it returns a count. However, it does not state whether this operation is reversible, whether it affects invoices in draft/sent states specifically, or whether it requires specific permissions — though most material behaviors are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all earning their place. Front-loaded with the primary action, then scope/exclusions in sentence two, and side-effect plus return value in sentence three. Zero waste, no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a bulk mutation with no annotations and no output schema, yet the description covers the action, scope, exclusions, side effects, and return value. It omits explicit permission requirements and rate-limit info, but given the moderate complexity and clear boundary conditions (unsent, non-ANAF, non-cancelled), the description is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (uuid, companyId) are already documented in the schema. The description adds context about what the operation does semantically with the client profile data, but doesn't add parameter-specific details beyond the schema's own descriptions. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Resync') applied to a specific resource ('unsent invoices') with a defined scope (rewrites older invoices, distinct from automatic propagation on client update). It clearly differentiates from the sibling invoices_sync_client by explicitly contrasting the 'current month only' behavior, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when this tool applies (unsent, not uploaded to ANAF, not cancelled invoices) and contrasts it with automatic propagation ('current month only'). It doesn't explicitly name an alternative tool for month-only syncing, but the invoices_sync_client sibling is clearly implied. The exclusion conditions (not ANAF-uploaded, not cancelled) provide strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It states the tool validates and returns validity status plus company details, which covers the external service dependency (EU VIES). However, it doesn't disclose behavior details like rate limits, VIES unavailability, network failure handling, or whether failures throw vs return status. For a read-only validation lookup with no annotations, the description is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, tightly packed with high information density. First sentence states what the tool does and returns; second sentence states when to use it. No filler, no repetition of schema content. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple validation lookup with only 2 params and no output schema. The description covers purpose, use-case, and return value sufficiently. It could slightly benefit from mentioning the response format/fields structure, but given the simplicity and full schema coverage, the description is adequately complete for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters have descriptive names/examples in the schema itself. The description adds meaningful context by explaining the validation is 'against the EU VIES system' and the purpose ('before applying reverse charge'), which frames how vatCode is used. The companyId parameter meaning (company UUID override) is fully covered by schema; the description adds the reverse-charge business context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Validate') with a clear resource ('VAT code against EU VIES system') and explicitly states output (validity + registered company name/address). It clearly distinguishes from siblings like anaf_validate_cif and clients_anaf_lookup, which target a different validation domain (Romanian ANAF vs EU VIES).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use it ('to verify EU intra-community VAT numbers before applying reverse charge'), which provides clear use-case context. However, it doesn't explicitly exclude alternatives or mention when NOT to use it versus anaf_validate_cif or clients_anaf_lookup, leaving the boundary with those siblings implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that CIF validation happens automatically and that official data is retrieved, which is useful behavioral context. However, it doesn't state what happens on validation failure, whether creation is idempotent, or whether this is a required first step before other company operations. For a creation tool this is decent but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. Each sentence adds distinct information: what the tool does and the CIF format flexibility. Well front-loaded with the primary action in the first clause.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter creation tool with complete schema coverage, the description covers the core behavior adequately. It explains the external integration (ANAF), the data pulled, and format flexibility. Minor gaps: no mention of output/return shape after creation, and no statement about validation failure behavior, but these are inferable for a create operation given the described flow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — the single 'cif' parameter is already documented precisely with an example. The description adds value by explaining how the CIF is used (validation + retrieval) and that the RO prefix is optional, which complements the schema's example rather than merely repeating it. The description also clarifies the tool-level behavior tied to this parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Create a new company') and adds valuable scoping detail: it validates the CIF with ANAF and retrieves official registration data. It clearly distinguishes from sibling tools like companies_update and companies_upload_logo.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the behavior triggered on creation (ANAF validation, official data retrieval), giving the agent context for what to expect. It doesn't explicitly name alternative tools or state when NOT to use this, but the distinct creation purpose is clear among sibling companies_* operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It states what data is returned (CIF, addresses, bank info, sync settings, ANAF token status), which is useful. However, it doesn't disclose pagination behavior, response format/granularity, or whether this is a read-only operation. For a zero-parameter list tool the risk is low, so a mid-range score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. The first sentence states the purpose and scope; the second lists the return content and names the downstream consumer tool. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with a well-known return shape (company details), the description covers the key information: scope, return fields, and usage purpose. No output schema exists, so the description's listing of return content (CIF, addresses, bank info, sync settings, ANAF token) is the primary transparency mechanism and is sufficient for agent decision-making. It could note pagination, but for a scoped list this is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema coverage (nothing to document). With no parameters, the baseline should be 4 per the rubric. The description adds clarity about return content details, which partially compensates even though there are no params to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('List all companies') with clear scope ('belonging to the authenticated user's organization'). It distinguishes from the sibling companies_get (single company) and companies_select tools by explicitly noting its purpose is to find company UUIDs for companies_select.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use it (to discover company UUIDs for the companies_select tool), which orients the agent. It doesn't explicitly state when NOT to use it, but for a list tool the implicit usage is clear and the reference to companies_select gives useful downstream guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that cancellation works from draft or issued status, that it preserves the historical record unlike deletion, and that the reason is optional. This is meaningful behavioral context for a state-changing operation. It doesn't describe the resulting status or effects on related documents, but the coverage is reasonable for the tool's scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: purpose, status eligibility, contrasting behavior with delete, and optional reason. No fluff, no repetition of parameter details already in the schema. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool operates on a single required parameter (uuid) with three optional ones, all documented at 100% schema coverage, and no output schema needed, the description provides good context by stating valid states, the historical preservation aspect, and optional reason. It covers the key decision factors an agent needs. Could mention the resulting delivery note status, but this is a minor gap given the modest complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents all 4 parameters (uuid, companyId, cancellationNotes, cancellationReason) with their own descriptions. The tool description adds context about cancellationReason being optional, which complements rather than duplicates the schema. Baseline 3 is appropriate since the schema handles parameter documentation adequately and the description confirms optionality.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb+resource ('Cancel a delivery note') with concrete intent ('when delivery will not occur') and even establishes valid statuses (draft or issued). It distinguishes from siblings like delivery_notes_delete by explicitly contrasting cancellation with deletion, making it distinct from related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use it ('when delivery will not occur') and distinguishes from deletion ('Preserves historical record unlike deletion'), implicitly pointing to when cancellation is preferred over delete. However, it doesn't explicitly name the alternative tool (delivery_notes_delete vs delivery_notes_storno) or state when NOT to use this tool in favor of another, so it's clear but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. 'Permanently delete' and 'Only draft delivery notes can be deleted' disclose irreversibility and the draft-only constraint, which are important behavioral traits. However, it doesn't disclose permission/authorization requirements or behavior on failure (e.g., what happens if attempting to delete a non-draft note) beyond the stated constraint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, perfectly front-loaded with the core purpose, no wasted words. Every element earns its place—the delete action, the draft-only constraint, and the alternative tool reference.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with 2 fully-documented parameters and no output schema, the description is quite complete. The draft-only constraint and audit trail guidance are important operational details. It could benefit from noting prerequisites (e.g., that the note must be in draft status) but the constraint is already stated. Adequately complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (uuid, companyId) having descriptions in the schema. The description itself adds no parameter-level detail beyond what the schema provides, so baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool permanently deletes a delivery note, with specific verb+resource. It also distinguishes itself by explicitly contrasting with 'cancel' for issued notes, which is a meaningful sibling differentiation since delivery_notes_cancel exists alongside delivery_notes_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when this tool IS appropriate (draft delivery notes only) and when it is NOT ('Use cancel for issued delivery notes to preserve audit trail'). This provides clear exclusions and directs to the alternative tool by name, exactly what the rubric rewards.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the disclosure burden. It states the tool lists messages (read-oriented intent) and enumerates categories but does not disclose pagination behavior details, authentication prerequisites, or what happens with default/missing parameters. For a read-side listing tool this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a tight two-sentence structure that conveys purpose, content scope, and use case with no filler. Every sentence serves a distinct function: defining the action and its platform scope, then enumerating content categories and practical utility.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a filtered list tool with 100% schema parameter coverage and no output schema, the description adequately covers the essential context: what is listed, where from, what filters exist, and why it's useful. It could note default ordering or whether results span the last N days, but this is sufficient for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all four parameters (page, limit, status, messageType) are individually documented in the input schema. The description contextualizes these by framing them as pagination and filtering capabilities and naming message categories that align with the enum values. This adds value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists e-Factura messages from the ANAF SPV platform with pagination and filtering. It enumerates the message types (responses, notifications, errors, warnings, informational) and specifies a concrete use case (troubleshooting invoice upload issues). This distinguishes it well from the sibling efactura_messages_get, which presumably retrieves a single message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states its purpose for troubleshooting invoice upload issues, framing when it would be useful. It implies a browse/list use case contrasted with efactura_messages_get (retrieval of a single message), though it does not explicitly name the alternative or give when-not-to-use guidance. Sibling names make the differentiation reasonably inferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and meaningfully discloses that the import runs asynchronously via a message queue and directs the user to check status with import_get. This is important because the result is not immediate and the agent wouldn't know to poll otherwise. It doesn't detail what success/failure looks like but covers the key async caveat.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with zero wasted words. Front-loaded with the primary action and precondition, with the asynchronous behavior and status check as a follow-up. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential async behavior and how to check progress, which are the two most important operational facts. No output schema exists so the description isn't expected to describe return format. The main gap is not stating any caveat about the async operation possibly timing out or failing, but for a sequencing-oriented tool it's fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all three parameters. The description adds the async execution context but doesn't elaborate on parameter semantics like what importOptions entries mean or the relationship between companyId and the active company. Baseline 3 is appropriate since the schema carries the parameter burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('execute an import job after mapping is confirmed'), identifies the specific resource (import job), and notes it runs asynchronously. This distinguishes it from import_preview, import_mapping, and import_upload among the import-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The precondition is explicit ('after mapping is confirmed'), which indicates this tool is the final step following import_mapping/import_preview. It points to import_get for status checking. It doesn't name alternatives explicitly but gives clear sequencing context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool returns base64-encoded data with MIME type, which is useful behavioral info. However, it doesn't mention size limits, whether downloads are reversible/safe (it's a read operation but not stated), or error handling for missing/unavailable attachments. Basic transparency, not necessarily full coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences covering function, return format, parameter sourcing, and supported file types. Zero filler, front-loaded with the core action, and every sentence adds specific value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward download retrieval tool with 3 well-documented parameters and no output schema, the description is reasonably complete. It covers the essential workflow (how to get attachment IDs, what's returned) and is consistent with the invoice attachment ecosystem. Could mention error conditions or how to handle the base64 response, but this is adequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema documents all parameters. The description adds value by explaining the relationship between attachmentId and the invoices_get attachments array, and the companyId parameter has a clear default behavior described in the schema itself. The description meaningfully connects the parameters to the surrounding workflow.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it downloads a file attachment from an invoice, with specific details on the return format (base64-encoded binary data with MIME type) and supported file types. It's clearly distinguishable from siblings like invoices_pdf and invoices_xml which generate or export documents, while this tool retrieves attached raw files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on where to obtain the required attachmentId (from invoices_get 'attachments' array), which is a practical pointer. It names the source tool for UUIDs but doesn't explicitly state when to use this vs alternatives like invoices_pdf or exports_download, so some exclusion guidance is missing but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that storno creates refund/credit-note invoices (a mutating operation) and mentions per-item error reporting. However, it doesn't state side effects like whether source invoices are destroyed, renumbered, or if there are cascade implications. For a mutation with no annotation coverage, some additional behavioral context (idempotency, reversibility, partial success behavior) would help, but the basics are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. Front-loads the purpose, states eligibility constraint, and the expected return value. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a batch mutation tool with 2 params, no output schema, no annotations. The description covers the core purpose, eligibility, and return shape. It's slightly thin on what 'storno' means for the target invoices (does it invalidate them? create a paired credit invoice) and failure behavior for partially-eligible batches, which matters for a batch operation with per-item errors. But overall it's usable as-is for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters comprehensively. The description adds the eligibility filter context (issued/validated only) which reinforces the ids parameter meaning. However, the description adds little beyond what the schema already states about ids and companyId, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates storno (refund/credit note) invoices for multiple invoices in batch. It defines the operation (storno creation), scope (multiple invoices), and distinguishes from single-invoice operations like invoices_cancel or delivery_notes_storno.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly specifies eligibility criteria: 'Only outgoing invoices with status issued or validated are eligible.' This tells the agent exactly when this tool applies and what conditions must be met. The sibling invoicing tools (invoices_cancel vs storno) are implicitly distinguished by the batch+storno specificity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It discloses the key behavioral facts: returns CSV text, includes UTF-8 BOM for Excel compatibility, and enforces a 10,000-invoice maximum. The limit disclosure is especially valuable since exceeding it presumably errors out. It doesn't fully describe error behavior or pagination handling beyond the cap, but the critical constraints are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero waste. Every sentence earns its place: the first defines the action, the second clarifies format detail (UTF-8 BOM), and the third provides a crucial limit plus an alternative tool pointer. Exceptionally efficient and well front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 10,000-row cap, no output schema, and zero annotations, the description covers the key return characteristics (CSV text, encoding) and the critical constraint (row limit) well. It correctly references invoices_list for filter semantics. Minor gaps: no mention of what columns are exported, whether sort/order affect CSV output, or specific error behavior on exceeding the limit. But for a filtered-export tool with a sibling reference, this is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 9 parameters. The description adds the fact that filters mirror invoices_list, which is useful orienting context, but doesn't add per-parameter semantics beyond the schema. Per the baseline rule for high coverage, a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Export a filtered list of invoices to CSV format' with a specific verb, resource, and format. It explicitly differentiates from the sibling invoices_export_zip by noting the 10,000-invoice limit and pointing large exports to the zip variant, which is the key distinction among export tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the use case (CSV export with Excel compatibility) and gives an explicit exclusion when to NOT use it ('use invoices_export_zip for large exports with files'). It references invoices_list filters as the parameter source. It doesn't enumerate exhaustive when-not scenarios but the main alternative is named clearly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It discloses key behavioral traits: asynchronous processing, returns exportId/statusUrl for polling, webhook option, Pro plan requirement, and 100-invoice cap. It doesn't mention the subsequent exports_download step to fetch the file, which is a minor gap given the related exports_download sibling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with zero waste. Each sentence earns its place: what it does, how it's async, and the constraints (Pro plan, cap). Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex async export tool with 6 params (including an enum), the description covers the key operational aspects well. With no output schema and no annotations, it explains the async workflow. It could mention the exports_download step for retrieving the resulting archive, which is a notable omission given it's the natural follow-up in the toolchain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all six parameters are documented in the schema. The description reiterates the max 100 invoiceIds and Pro requirement for includePdf, adding marginal value. It doesn't add meaning beyond the schema for folderStructure, includeCsv, includeXml, or companyId, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (export), the resource (invoices by UUID list), the output format (ZIP with PDFs, XMLs, CSV summary), and distinguishes from siblings like invoices_export_csv and invoices_export_efactura_zip by specifying the ZIP+bundle nature. It's specific and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains it's asynchronous (returns exportId and statusUrl, poll or webhook), requires Pro plan, and caps at 100 invoices. It doesn't explicitly contrast with the alternative export tools (e.g., invoices_export_csv, invoices_export_efactura_zip) but the async/bundle/plan details give clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the operation is irreversible ('cannot be edited'), that PDF generation is plan-dependent ('Pro plan'), and enumerates the full pipeline of side effects (validation, series assignment, XML generation, status change). This is rich behavioral disclosure beyond what any schema conveys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence followed by a single clarification sentence. It is efficient with no wasted words, covering purpose, behavior, side effects, and the alternative tool in compact form. It earns a high score, though it could be slightly more scannable with bullet points for the pipeline steps.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a state-changing tool with no annotations and no output schema. The description fully enumerates the transformation pipeline (validate, assign series, generate XML, generate PDF, change status), the irreversibility, the plan-dependency for PDF, and the follow-up action (invoices_submit). Given the tool's complexity and the absence of structured metadata, the description is thorough and complete for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (uuid, companyId) are documented in the schema. The description adds context about the two parameters implicitly: uuid is the target invoice and companyId is an 'active company' override. However, it doesn't add details about companyId's meaning beyond 'uses active company if not set' which is in the schema itself, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: 'Issue a draft invoice.' It enumerates specific actions performed (validate data, assign series number, generate UBL 2.1 XML, generate PDF, change status). This distinguishes it from siblings like invoices_submit (sends to ANAF) and invoices_create (creates draft), providing clear scoping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the state transition ('changes status from draft to issued') and warns 'Once issued, the invoice cannot be edited.' It also directs the user to use invoices_submit for ANAF e-Factura submission, which is a clear alternative pointer. It doesn't explicitly state when NOT to use this tool, but the irreversible consequence plus the sibling pointer provides strong contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the base64-encoded binary return format with content type (useful behavioral info), the Pro plan requirement, and the generation mechanics (auto on issue or on-demand first request). This is helpful behavioral context beyond what schema/annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with zero waste. The description front-loads the primary action (Download the PDF representation), then adds essential behavioral details (format, plan requirement, generation timing). No fluff or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 params, no output schema, no nested objects), and the description covers the action, return format, prerequisite (Pro plan), and generation behavior. For a straightforward download tool it's reasonably complete. Slight gap: it doesn't mention error conditions (e.g., not found, premium required) but that's acceptable for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters (uuid and companyId) documented in the schema itself. The description adds the companyId override behavior context ('uses active company if not set') implicitly, but the schema already documents this. Baseline 3 is appropriate since the description doesn't add much beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool downloads a PDF representation of an invoice, with a specific verb (Download) and resource (PDF of invoice). It distinguishes from sibling tools like invoices_export_csv, invoices_xml, and proforma_invoices_pdf by being explicitly the PDF download for invoices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use it (download invoice PDFs) and notes the Pro plan requirement as a gating condition. It doesn't explicitly name alternatives or state when not to use it, but the sibling landscape shows distinct PDF tools for proforma and delivery notes, making the intent clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the status change to 'sent_to_provider' and the asynchronous validation behavior with polling suggestions. It could note side effects more richly but covers the key behavioral trait well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with zero waste. States action, precondition, state transition, and follow-up in economical prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, this description covers the essential behavioral facts: status requirement, status transition, and asynchronous outcome. Could mention failure/validation error paths, but is reasonably complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. Both parameters (uuid, companyId) are documented in the schema. The description adds the companyId override semantics implicitly via the broader tool context but doesn't add explicit parameter-level guidance beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear specific verb+resource: 'Submit an issued invoice to the ANAF e-Factura system.' It clearly scopes to submission of invoices, distinguishes from siblings like einvoice_submit and invoices_issue by naming the target system and prerequisite status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the required precondition ('must be in issued status') and explicitly directs the user to poll invoices_get or invoices_events for validation results. It lacks explicit exclusions (e.g., when NOT to use), but the required-status hint provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It correctly identifies the tool as a mutation (create/update), states the plan restriction, and discloses the password-preservation behavior on update. Doesn't mention SMTP connectivity failures or validation behavior, but covers the key behavioral contract.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with zero waste. Front-loads the core purpose, adds the important plan restriction immediately, then discloses the critical password-omission behavior. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a config mutation with 8 well-documented parameters (100% schema coverage), the description adequately covers purpose, plan gating, and the key update nuance. No output schema means return value isn't described, but for a write operation this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed per-parameter descriptions, so the schema does the heavy lifting. The description adds the password-omission update nuance and the 'fromAddress must be authorized' context is already in the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Create or update the organization's custom email sender'. Explicitly states it's Business plan only and that invoices/receipts/delivery notes go through this SMTP server. Distinguishes from sibling mailer_config_get/delete/test by declaring it's the create/update counterpart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the Business plan constraint and that this config affects email sender behavior for business documents. Notes the password-omission convention for updates. Doesn't explicitly contrast with mailer_config_get/delete/test, but the plan restriction and idempotent create/update nature give useful context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly discloses the soft-delete behavior, data preservation, and login prevention. It also states exclusions (cannot deactivate self, owner, or super admins). This is good behavioral disclosure that exceeds the bare minimum for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, zero waste. Front-loaded with the primary purpose and immediately followed by behavioral notes. Every sentence adds value—the soft-delete nature, data preservation, and constraints are all packed efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter mutation tool with no output schema and no annotations, the description provides solid context: what the operation does, what it does NOT do (permanent deletion), and its constraints. The return value isn't specified but for a simple delete operation with a single uuid parameter, acceptable. No nested objects or complex behaviors need further explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage with 'Member UUID to deactivate' for the uuid parameter, which is self-explanatory. The description doesn't add parameter-specific meaning beyond what the schema gives, but given the single simple parameter and 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear specific verb+resource: 'Deactivate (soft-delete) a member from the organization.' It explicitly distinguishes soft-delete from hard delete by stating it preserves historical data. The tool name members_delete together with the description clearly identifies the action and differentiates from other member tools like members_update and members_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful context about what deactivation entails (preserves data, prevents login), implying this is the right tool for removing access while keeping records. It doesn't explicitly name alternative tools or state when NOT to use it (e.g., when permanent removal is needed), but the soft-delete framing gives reasonable context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the operation is idempotent and resets the unread count to zero, which are useful behavioral disclosures. Mentioning idempotency adds meaningful transparency for an agent considering repeated calls. Could additionally mention whether it returns a count or ack, but what's present 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero filler. Each sentence earns its place: action+scope, effect on unread count, idempotency guarantee. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, the description is complete. It covers scope, side effects (unread count reset), and idempotency behavior. The absence of output schema means return values are unaddressed, but for a bulk mark-read operation this is a minor gap. With no annotations, the description does sufficient work.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100% (trivially complete). The description correctly notes there are no parameter requirements. With no parameters, there is nothing for the description to add beyond confirming the no-argument nature, which it effectively does.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Mark all notifications as read'), the resource (notifications), and the scope (all for authenticated user). It distinguishes from siblings like notifications_mark_read (singular) and notifications_unread_count (read-only count).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes 'in a single operation' and 'for the authenticated user,' giving context on scope and batching. It implicitly distinguishes from notifications_mark_read (single) but does not explicitly name alternatives or state when not to use it. Adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral disclosure burden. It usefully discloses that the client secret is returned only once (store it securely) and that the tool cannot be called via API key or OAuth2 token (requires browser session JWT) — both are important behavioral constraints beyond what the schema reveals. However, it doesn't clarify consequences of invalid scopes (whether the call fails or silently downgrades) or any rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, tightly packed with genuinely useful information. The auth-requirement disclosure and the one-time secret warning are high-value additions. No filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the tool must disclose the return value behavior — it does highlight the one-time client secret, which is the key output concern. Schema coverage is 100%, and the 7 params are self-explanatory given the domain. For a create operation with good param documentation and the critical side-effect (secret) disclosed, this is reasonably complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 and the schema does the heavy lifting. The description adds no per-parameter detail beyond the schema, but the schema's own descriptions are clear (e.g., clientType enum distinguishes confidential vs public). The description's one-time-secret warning provides context for the confidential clientType implications, which adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Uses a specific verb+resource ('Register a new OAuth2 application') and clarifies it's a third-party integration. This clearly distinguishes it from sibling tools like oauth2_clients_list, oauth2_clients_get, oauth2_clients_revoke, and oauth2_clients_rotate_secret. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear contextual guidance: it states the authentication requirement (browser session JWT, not API key or OAuth2 token), which serves as an important usage boundary. However, it doesn't explicitly state when to use this over alternatives or when not to use it — though the create vs. list/get/revoke/rotate naming makes that self-evident. The auth constraint is the most valuable usage guidance here.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral disclosure burden. It clearly discloses that the action is irreversible ('This action is irreversible') and states the authentication restriction. It covers the critical behavioral traits well, though it doesn't mention what happens to existing integrations or whether this affects the caller's own session tokens.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero filler. The first sentence states the action and its scope; the second adds irreversibility and authentication constraints. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter mutation tool with no output schema, the description covers the essential ground: what it does (revoke app + tokens), its irreversibility, and its auth constraint. A small gap exists around the side effects on the revoking user's own tokens/integrations, but the core information is complete for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the sole parameter 'uuid' is documented as 'OAuth2 app UUID'. The description adds no additional parameter context beyond the schema, which is the baseline-3 scenario per the rubric since the schema already fully documents the single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Revoke' and the resource 'OAuth2 application', and specifies the scope of the action ('all its associated access and refresh tokens'). It distinctly differentiates from sibling tools like oauth2_clients_create, oauth2_clients_update, and oauth2_clients_rotate_secret.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Cannot be called via API key or OAuth2 token', which is important usage guidance about authentication constraints. It doesn't explicitly name alternatives or when-not-to-use scenarios relative to siblings, but among OAuth2-related siblings the destructive revoke action is clearly distinguished by context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It appropriately describes the ordering behavior (most recent first), the returned fields, and the relationship between payments sum and invoice amountPaid/balance. It frames this as a read operation implicitly. Could add pagination or error behavior but covers the core behavioral contract.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero waste. The description is front-loaded with the core purpose and ordering behavior, followed by return fields and the business-rule relationship to balance. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple filtered-list tool with 2 fully documented parameters and no output schema, the description is complete. It covers what's returned, ordering, and the financial relationship to amountPaid/balance. Lacks only pagination details, but this is 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, both parameters (companyId and invoiceId) are described in the schema. The description adds the invoiceId as the required scoping parameter but doesn't add meaning beyond the schema's own descriptions. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all payments for a specific invoice, ordered by payment date descending. It specifies the returned fields (amount, date, method, reference number, notes) and distinguishes it from payments_create/payments_delete siblings. The verb+resource+scope is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description accurately identifies the tool as a read operation scoped to a single invoice. It doesn't explicitly name alternatives or exclusions, but the context makes clear this is the payment-list viewer distinct from payment mutation tools. Sibling differentiation is implicit via the read-only framing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It makes clear this is a non-destructive preview operation that generates HTML output with sample data. However, it doesn't disclose what 'sample invoice data' contains, whether the preview reflects currently-saved config or only the overrides passed in parameters, or what happens with missing company context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, and zero wasted words. The first sentence states what it does and the second states when to use it. This is exemplary conciseness for a description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple (4 optional params, no nested objects, no output schema), and the description covers the core purpose and primary use case. Given no output schema, it doesn't describe the return format, which would be helpful for an HTML-returning tool. For a preview tool of this simplicity, the description is reasonably complete but could mention the response format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents all four parameters well. The description adds the key context that these parameters are preview overrides ('companyId overrides configured default' is in schema, but description frames all params as representing the prospective config). It doesn't repeat schema details redundantly, which respects the high coverage baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource combination ('Generate an HTML preview of a PDF template') and clearly states the scope ('with sample invoice data'). It distinguishes from siblings like pdf_template_config_update and pdf_template_config_get by clarifying this is a preview action, not a read or write of config.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use it ('preview how a template will look before saving configuration changes'), which gives clear usage context. It implies it should be used before pdf_template_config_update but doesn't explicitly name alternatives or state when NOT to use it. Still, the 'before saving configuration changes' framing provides strong contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral burden. It does well by disclosing the non-destructive side effect on products (categoryId set to null, products retained), which is key behavioral context. It does not mention reversibility or permission requirements, but the core consequence is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that states the action and its most important consequence with zero filler. Every phrase adds meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete operation with simple parameters and no output schema, the description adequately covers the essential consequence behavior. It could mention reversibility or permission requirements, but the core behavioral contract (what gets destroyed, what remains) is clearly communicated, which is sufficient for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters ('uuid' and 'companyId') are already documented in the schema. The description adds no parameter-specific guidance beyond what the schema states, but the schema fully covers parameter meaning, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') with a clear resource ('product category') and explicitly distinguishes the scope: only the assignment is removed, products are not deleted. This clearly differentiates from sibling tools like product_categories_create/update/list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly communicates the destructive nature and its behavioral consequence (categoryId set to null), but it does not name specific alternatives or when-not scenarios. There are no other category delete tools, so sibling differentiation is minimal, but it clearly scopes the effect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It adds useful context about ordering and the fallback colour swatch role, but as a list operation it's inherently read-only and low-risk. It doesn't describe pagination, limits, or response shape, which are the main gaps for a list tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. The first sentence states purpose and ordering; the second adds functional context (chip strip, fallback colour swatches). Every phrase earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward list tool with one optional parameter and no output schema, the description covers purpose, ordering, default scope, and functional role. The only gap is no mention of pagination or response format, but for a likely modest set of categories with no output schema requirements, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the single companyId parameter documented. The description adds meaningful context beyond the schema by explaining the 'active company' default behaviour and that the parameter is an override, which is more than the schema alone conveys. For a single optional parameter, this is strong.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource ('List all product categories for the active company') and specifies ordering (sortOrder then name). It distinguishes the tool from the sibling CRUD tools (product_categories_create/update/delete) by being the list variant, and provides functional context about where categories appear (chip strip above POS product grid).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clarifies it operates on the 'active company' by default with an optional companyId override, giving clear context on when the tool applies. It doesn't explicitly state when NOT to use it or name alternative tools, but for a simple list operation the implied usage (when you need product categories) is clear enough relative to the sibling create/update/delete variants.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It clearly discloses partial-update behavior (only provided fields change) and the null-to-clear convention for code and other nullable fields. Does not mention whether updating isActive or companyId has side effects (e.g., on related fields), but the core mutation semantics are well documented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly-woven sentences: action+semantics, usage scenarios, and null convention. Zero filler, front-loaded with the single most important fact (partial update). Each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a partial-update tool with 16 optional parameters and full schema coverage, the description sufficiently covers the update-by-UUID model, the null-clearing convention, and practical use cases. No output schema exists but a PATCH-style update tool's return value is typically predictable; the description adequately compensates for the parameter richness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter already has its own description. The tool description itself repeats the 'pass null to clear' pattern but the schema already documents this per-field. The description adds a usage-level note (assigning codes for grouping, defaults on sync-created products) that helps, but the schema carries most parameter meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource ('Update an existing product by UUID'), states the partial-update semantics up front, and lists specific use cases (assigning product codes for grouping per plan/SKU, fixing names, adjusting prices on sync-created products). Distinct from products_create/list/get 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states all fields are optional and only provided fields change, and gives concrete scenarios (assigning SKUs, fixing names, adjusting prices). Doesn't explicitly name an exclusion (e.g., when to use create instead for non-existent products), but the partial-update framing strongly implies correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses the return format (base64-encoded binary data) and a hard requirement ('Requires Pro plan'). However, it does not describe whether this is a read-only operation, response size limits, or what happens on a non-existent UUID. For a download tool, the disclosed return format and plan requirement provide meaningful but partial context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. Every clause adds value: the verb, resource, return format, and access requirement. This is optimal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward download tool with 2 well-described parameters and no output schema, the description covers the essential use case. The base64 format disclosure is helpful. The main gap is lack of error/behavioral detail (e.g., what happens for expired/non-existent invoices), but the tool's simplicity keeps the completeness bar reasonable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with uuid and companyId both described in the schema. The description adds the 'Requires Pro plan' constraint and the base64 return format context, which complements the schema. The 'companyId overrides configured default' nuance is schema-provided, so the description adds limited additional parameter depth but supplements with return-format and access requirements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Download'), the resource ('PDF of a proforma invoice'), and the output format ('base64-encoded binary data'). It distinguishes from sibling tools like delivery_notes_pdf or receipts_pdf by the explicit 'proforma invoice' resource naming.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly conveys when to use this tool (when needing the PDF of a proforma invoice, as opposed to create/list/update/delete siblings for the same resource). No explicit exclusions or alternative recommendations are given, but the resource scope is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that it bypasses scheduled generation and importantly states 'Does not update the nextIssuanceDate' — a meaningful side-effect disclosure that helps the agent understand consequences. It doesn't mention whether the action is reversible or requires confirmation, but the key behavioral traits are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with zero wasted words. It front-loads the action, explains the use case, and discloses a key side-effect. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 well-documented parameters, no output schema, and no nested objects, this description is complete. It covers purpose, use case, and the critical side-effect of not updating nextIssuanceDate. It could mention return values or what the generated invoice looks like, but for a straightforward trigger action this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (uuid and companyId) are already fully documented in the schema. The description adds context about the uuid being a 'recurring invoice template' but doesn't add meaning to companyId beyond what the schema provides. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Manually trigger immediate invoice generation from a recurring invoice template') and clearly distinguishes itself from scheduled generation. It also clarifies it's for testing or one-off invoices, differentiating it from sibling tools like recurring_invoices_update, recurring_invoices_toggle, and recurring_invoices_bulk_issue_now.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use it ('useful for testing configurations or creating one-off invoices') and clarifies a key behavioral exclusion ('bypassing the scheduled generation'). While it doesn't name alternative tools, the sibling set includes recurring_invoices_bulk_issue_now which is implicitly distinct. It doesn't explicitly state when NOT to use it, but the purpose statement is clear enough for proper selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses what's returned (percentage, label, e-Factura category, default flag) and the sort order, which is helpful. However, it doesn't mention read-only semantics explicitly, authorization requirements, or pagination behavior. For a read-only list tool this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the core purpose first and adding contextual examples. Every sentence earns its place — the first states purpose+scope+sort, the second lists return fields plus practical Romanian rate context. No waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple list tool with 1 parameter and no output schema. The description names the return fields which partially compensates for the missing output schema. For a low-complexity tool, this level of description is reasonably complete, though a note on pagination or the read-only nature would push it to 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (companyId is fully described in the schema as 'Company UUID override uses active company if not set'), so baseline is 3. The description adds value by clarifying the 'active company' default behavior consistent with the schema, but doesn't add much beyond it. The single parameter is both in schema and described well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb+resource ('List all VAT rates configured for the active company') and specifies the sort order and return fields. It distinguishes from sibling tools like vat_rates_create/update/delete by being a list operation, and the scope ('active company') is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly sets context: it operates on the active company by default, and mentions the companyId override. It provides useful contextual examples (common Romanian rates) that help an agent understand when this is relevant. It doesn't explicitly state when NOT to use it vs alternatives, but the scope is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries some burden. It discloses that results are paginated and filterable, which is useful. However, it does not describe return format, ordering, error behavior, or rate limits. For a read-only listing tool the gap is moderate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. First sentence states the core purpose and capability, second sentence provides the sibling-tool pointer. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with 100% schema coverage and a clear pointer to the detail tool, the description is largely complete. It could mention default ordering or that delivery attempts return summary data only, but these are minor gaps given the schema richness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 8 parameters. The description adds minimal parameter-level value but mentions the status/event/date filtering options at a high level. Baseline 3 applies given complete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Retrieve a paginated list of delivery attempts for a webhook endpoint.' The description distinguishes purpose well and explicitly references sibling tool webhooks_delivery_detail for deeper inspection, setting it apart from related webhook tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States when to use (list delivery attempts) and explicitly points to webhooks_delivery_detail for payload inspection - an explicit alternative. Filtering capabilities (status/event type/date range) are enumerated, giving clear context on use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose one important behavior: the secret is always masked in the response, and it directs users to webhooks_regenerate_secret for a full secret. This is a genuinely useful behavioral disclosure for a read tool, though it doesn't describe the rest of the response fields or any 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both information-dense, no filler. The first states the core purpose and the second discloses the masking behavior with a pointer to an alternative tool. Excellent front-loading of the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-resource retrieval tool with a straightforward purpose, this description is reasonably complete. It explains the retrieval scope ('full configuration'), discloses the mask behavior, and names the alternative for obtaining a full secret. No output schema exists, and the description doesn't describe the full response structure, but for a config-get operation this is minimally sufficient. The masking caveat is the most important edge case and is handled well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers both parameters at 100% (uuid as 'Webhook endpoint UUID' and companyId as 'Company UUID (overrides STORNO_COMPANY_ID env var)'). The description doesn't add much parameter-specific meaning beyond what the schema already documents, but with 100% coverage the baseline of 3 is appropriate. The description's mention of 'single webhook endpoint' indirectly reinforces that uuid identifies one endpoint.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource pattern: 'Retrieve the full configuration of a single webhook endpoint.' This clearly distinguishes it from webhooks_list (which returns multiple), webhooks_delete (writes/destroys), and webhooks_regenerate_secret (modifies the secret). The scope ('single', 'full configuration') adds precision that differentiates it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description names webhooks_regenerate_secret as the alternative to use when a full secret is needed, which is a helpful pointer. However, it doesn't explicitly state when to prefer this tool over webhooks_list, nor does it discuss when NOT to use it. The sibling 'get' pattern in this API (e.g., invoices_get, delivery_notes_get) implies single-resource retrieval, but the description could more explicitly differentiate from the list variant.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses that this is a write/creation operation (balance implications), explains side effects (demoting existing defaults, enabling cash-register tracking), and notes the openingBalance becomes locked once set. It does not explicitly state destructive risks or whether deletion/rollback is possible, but the creation semantics are well-covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-organized paragraph that front-loads the core purpose, then covers key business rules. It's information-dense with every sentence adding value, though it's somewhat long and could potentially be broken into clearer structured points. No wasted words or tautological content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 optional parameters, no output schema, and no annotations, the description does substantial work: it covers the bank vs cash semantics, unique constraints, default demotion, opening balance behavior. It could be more complete regarding what happens after creation (return value, whether the bank account is immediately usable) and could benefit from listing a prerequisite (e.g., active company required), but it exceeds the minimum viable standard comfortably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema by explaining the dependencies between parameters (openingBalance/openingBalanceDate enable cash-register reporting, IBAN required for bank), the locking behavior of openingBalance, and the uniqueness constraint on IBAN. It explains the isDefault demotion side-effect, which the schema does not mention.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb+resource ('Add a new bank account to the active company') and distinguishes between bank and cash account types, which differentiates this tool from bank_accounts_update and bank_accounts_list siblings. It explains key business rules (unique IBAN, one cash account per company, default demotion).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use type=bank vs type=cash and explains the implications (IBAN required for bank, cash-register tracking for cash). It explains the one-cash-account-per-company constraint and default demotion behavior, though it doesn't explicitly name alternative tools or state when NOT to use this tool. The distinction between bank and cash accounts within the same description serves as implicit usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does disclose the key behavioral trait: that this sets the X-Company header that will affect all subsequent company-scoped requests. It also notes the session-scoped nature of the selection. It doesn't mention persistence/across-session behavior, but the session-scoping is clearly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: what it does, how it works (X-Company header), and prerequisite. Zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, side-effect-note tool, the description fully covers the mechanism (header setting), the prerequisite (companies_list), and the scope (session-wide effect on subsequent requests). No output schema needed for a side-effect operation. This is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter (companyId) is well-described in the schema. The description reinforces that the companyId is a UUID and explains its session impact, but doesn't add substantially beyond the schema since the schema itself already explains this is the active company context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (select), resource (active company for session), and the mechanism (sets X-Company header). It distinguishes from sibling companies_create/update/delete by focusing specifically on session active-company selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to call companies_list first to find available company UUIDs, which is useful prerequisite guidance. However, it doesn't mention when selecting is necessary vs. when the default company context applies, or that this is a session-scoped action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states this is a mutation (PUT, sets active state), that it returns the updated company list, and that it requires COMPANY_EDIT permission. It's clear this changes organization-wide state. While it doesn't specify whether this action is reversible, the description covers the key behavioral traits: side effect (state change), required permission, and return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact 3-sentence structure: what it does, the endpoint and return behavior, and the prerequisite permission/usage hint. Every sentence carries meaningful information. Slightly denser than strictly necessary (endpoint path could arguably be redundant with the tool's purpose), but it stays efficient and front-loads the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with complete schema coverage and no output schema, the description is reasonably complete: it discloses the mutation, the permission requirement, the return value, and the standard prerequisite (companies_list). Given the simplicity of the operation, this is sufficient. The only minor gap is not specifying behavior in edge cases (e.g., invalid companyId), but that's typically unnecessary for such a tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents the companyId parameter. The description adds value by explaining the parameter's role ('mark as the active company for the organization'), the endpoint format ({uuid} in the path), and by telling the user to find UUIDs via companies_list. This complements the schema's field description rather than merely repeating it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action (set active company by UUID), the HTTP endpoint (PUT /api/v1/companies/{uuid}/set-active), and its return value (updated list of all companies). It distinguishes itself from siblings like companies_set_active vs companies_select (which likely involves user context switching) and companies_toggle_sync (toggling sync, not active state). The verb+resource+scope is specific and clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage directive: 'Use companies_list first to find available company UUIDs', which establishes a prerequisite workflow. It states the required permission (COMPANY_EDIT) and implies this operates at the organization level. However, it doesn't explicitly articulate when NOT to use it vs alternatives like companies_toggle_sync or companies_select, though the prerequisite and endpoint detail offer reasonable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It discloses that the tool performs a create-or-update (upsert) behavior, that it enables a provider, and sets credentials. It documents provider-specific config requirements (xrechnung, sdi, ksef, facturx). However, it doesn't disclose defaults behavior for the enabled flag or what happens on validation failure, though the config format specificity is substantial behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a dense single sentence with a clear lead clause then a structured enumeration of provider-specific configs. Every sentence earns its place. It could arguably be broken into a bulleted list for readability, but the content is efficient with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderately complex tool with 4 parameters (all covered in schema) and nested objects, the description covers the critical ambiguity: what exact config keys each provider expects. The companyId default behavior is noted in schema. The anaf exclusion is clear. It lacks stated return/output info, but since there's no output schema and the tool is a config saver (create/update), the primary missing piece would be error/validation behavior, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema description coverage, the description adds significant value by detailing exactly which JSON keys each provider requires — clientId/clientSecret for xrechnung, certPath/certPassword OR apiEndpoint/apiKey for sdi, authToken/nip for ksef, clientId/clientSecret/siret for facturx. This goes well beyond the generic 'Provider-specific configuration as JSON object' schema text. The description also clarifies that ANAF config is NOT managed here, a valuable semantic distinction.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb-resource pairing: 'Create or update an e-invoice provider configuration for a company' and 'enable a provider and set API credentials.' It clearly distinguishes from sibling tools like einvoice_config_list (listing), einvoice_config_delete, and einvoice_providers (discovery). The description also explicitly names the config structure per provider.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Use this to enable a provider and set API credentials,' giving clear context for when to invoke. It also notes ANAF config is 'managed separately via ANAF tokens,' an implicit exclusion that steers the agent away from using this tool for ANAF. However, it doesn't explicitly name alternative tools or state when NOT to use it beyond the ANAF caveat.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations were provided, so the description carries the full burden. It discloses what the tool does (validates credential authentication), the specific auth mechanisms per provider (ZRE OAuth2, intermediary API/cert, session init, Chorus Pro OAuth2), and explicitly excludes ANAF with rationale. It could note that the test has no side effects (doesn't persist anything) beyond the 'before saving' framing, but the core behavioral disclosure is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused paragraph of 4 sentences, front-loading the primary purpose and following with provider support details. Every sentence earns its place. Slightly dense but appropriate for a tool that supports multiple provider variants.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters with full schema coverage and nested objects. The description covers provider support, auth flows, and the ANAF exclusion. As a test action (validates connectivity), return-value semantics are less critical, though it could mention whether it returns pass/fail or detailed error info. Given high schema coverage and clear provider mapping, the description is largely complete for this tool's purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description adds meaning by mapping each provider to its supported credential shapes (xrechnung:{clientId,clientSecret}; sdi:{apiEndpoint,apiKey} or {certPassword}; etc.), complementing the config schema. It also adds context for the ANAF exclusion that relates to the provider enum. The companyId is implied as optional context but not detailed in the description beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool tests an e-invoice provider connection with given credentials before saving, validates authentication, and enumerates the supported providers with their specific auth methods. This distinguishes it from siblings like einvoice_config_save (saving) and storage_config_test (testing storage instead of e-invoice providers).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states it's for testing BEFORE saving credentials, and enumerates exactly which providers are supported along with their auth flows. It also notes ANAF uses a separate OAuth flow and cannot be tested here, which provides a useful exclusion. However, it doesn't explicitly contrast with alternatives like einvoice_submit or einvoice_providers, though the purpose is reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. The description discloses permanent destruction ('Permanently delete'), the constraint about last/default template, and the non-effect on already-sent emails. This is strong behavioral disclosure for a destructive operation, though it doesn't mention whether auth/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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all carrying meaningful information with zero waste. The description is front-loaded with the primary purpose and then adds constraints and side-effect clarity. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema and no annotations, the description covers the essential operational details: permanence, constraints on deletion, and non-effect on sent emails. It could mention whether the operation is idempotent or what happens with the template in active use, but overall it's fairly complete for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with 'uuid' and 'companyId' documented in the schema. The description adds no new parameter-level detail beyond the schema. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Permanently delete') and resource ('an email template'), and notes the permanent/destructive nature of the action. It distinguishes this from email_templates_update and email_templates_create by making the delete-specific behavior explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when NOT to use the tool: 'Cannot delete the last remaining template or the default template (set another as default first)'. This gives the agent critical operational guidance for when the operation would fail and how to work around it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that payment records are created for each invoice's remaining balance, implies mutation (marks as paid, creates records), states the default paymentMethod, and notes per-item error reporting. It could add whether this is reversible or has idempotency behavior, but the disclosed effects are reasonably complete for a batch mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no fluff; front-loaded with the core action, then key behavioral details, then return value. Concise and efficient, though it could arguably be slightly more structured around edge cases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 stating the return format (count of updated invoices and per-item errors). It covers the batch semantics, default payment method, and balance handling. For a batch mutation with 4 params and no output schema, this is reasonably complete, though it could note limits (max 100) which are in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds value by explaining the remaining-balance semantics (payment records for remaining balance), the default of bank_transfer, and that paymentMethod applies to all invoices uniformly. This goes beyond the schema's simple property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (mark as paid), resource (multiple invoices), scope (batch/full payment), and side effects (creates payment records for remaining balance). It distinguishes from single-invoice actions like invoices_cancel or invoices_bulk_cancel by specifying full payment and balance handling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains it creates payment records for remaining balances and returns counts plus per-item errors, giving clear context for when to use it for bulk payment processing. It doesn't explicitly contrast with alternatives like invoices_bulk_cancel or individual payments_create, but the clear purpose makes the appropriate use case evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses irreversibility ('This action is irreversible') and the draft-only restriction, which is valuable. However, it doesn't mention what happens to associated data (attachments, events, etc.) or whether any permissions are needed beyond the delete operation, given the adjacent invoices_restore sibling exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, zero wasted words. Front-loaded with the core action, then the constraint, then the irreversibility warning, then the alternative. Perfectly scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete tool with full schema coverage but no annotations and no output schema, the description covers the essentials: irreversible destructive action, draft-only scoping, and sibling alternative. It could note side effects on linked records or what a successful deletion returns, but given the simplicity of a delete operation, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented in the schema. The description adds context by explaining the draft-only constraint that governs which invoices are valid candidates. It doesn't add parameter-level detail beyond the schema, but the schema is fully sufficient, warranting a solid score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Permanently delete a draft invoice.' States the exact status constraint ('Only invoices with status draft can be deleted') and explicitly references the sibling alternative invoices_cancel for issued invoices, distinguishing it from similarly-named sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when this tool applies (draft invoices only) and when not to use it, naming the alternative: 'For issued invoices, use invoices_cancel instead.' This is textbook usage guidance with a clear exclusion and alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool transitions status from cancelled to draft, explains restrictions on when restoration is possible (ANAF submission, credit notes, payments), and notes the invoice becomes editable/reissuable afterward. It doesn't detail error responses or side effects on related records, but the core behavioral contract is well stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all information-dense with no filler. The constraints are front-loaded ('Only for accidental cancellations') and the conditions are listed concisely. Slightly verbose with the trailing sentence but earns its place by explaining the post-restore consequence. Could be trimmed slightly but is efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a targeted mutation tool with a simple 2-parameter schema and no output schema. The description covers purpose, constraints, and post-condition. It could add details about what happens to the cancellation reason, timestamps, or whether a draft series/number is preserved, but for its simplicity it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both uuid and companyId are already documented in the schema. The description doesn't add nuance beyond what the schema states — uuid is 'Invoice UUID to restore' and companyId is the override. Baseline 3 is appropriate per the rubric since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (restore a cancelled invoice), the target (back to draft status), and the specific resource (invoice). It distinguishes from siblings like invoices_cancel and invoices_bulk_storno. The verb+resource+outcome structure is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Only for accidental cancellations' and lists three conditions that block restoration (submitted to ANAF, has credit notes, recorded payments). It also states the follow-up: 'The invoice can then be edited and reissued.' This provides clear when-to-use guidance and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. The description honestly reveals that this is not purely a read operation — it may create a default config on first call ('Creates a default config if none exists'). This is a valuable behavioral disclosure that prevents surprise. However, it doesn't specify auth requirements or what happens with the companyId override parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both informative. The first sentence states purpose and return contents; the second reveals the important create-on-miss side effect. No wasted words. Slightly could be improved by front-loading even more, but it's already tight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-style config getter with a single optional param and no output schema, the description is reasonably complete. It lists what fields are returned, states the scoping (current company), and discloses the side effect. Gaps: no mention of auth requirements, and no details about what a default config looks like when created, but for a getter this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with only one optional parameter (companyId). The description explains the companyId semantics implicitly through 'current company' and the schema states 'overrides configured default.' Since the description covers 'current company' context and the schema fully documents companyId, the combination is adequate. With only one well-documented parameter, the burden is low.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get'), resource ('PDF template configuration'), and scope ('for the current company'). It enumerates exactly what data is returned (template slug, primary color, font, logo/bank info visibility, footer text, custom CSS), which distinguishes it well from siblings like pdf_template_config_update (mutator) and pdf_template_config_templates (listing available templates).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes clear context: this retrieves settings for the current company, and notably mentions 'Creates a default config if none exists' — a critical side-effect behavior an agent must know. It doesn't explicitly state when to prefer this over siblings, but the read-vs-write distinction from pdf_template_config_update is self-evident. A small gap: no explicit exclusion of 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It explicitly states core data (name, CUI) is read-only from ANAF, which is a useful behavioral trait that reveals the read-only nature of core fields. However, it does not disclose what happens with the invoice history portion (whether it is also read-only), response structure, or any auth/permission requirements. The description adds some value but omits meaningful behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. The first sentence states the primary function and scope, the second clarifies the data provenance. Every clause earns its place with no fluff or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-param retrieval tool with 100% schema coverage and no output schema, the description covers purpose, scope of returned data, and data provenance. It doesn't explain the return format (response structure of invoice history), but since there's no output schema, some detail on what gets returned could help. Still, for a read tool with two well-documented params, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters (uuid and companyId are documented in the schema). The description adds contextual meaning by clarifying that companyId 'overrides configured default,' which is already in the schema. Since coverage is high, the baseline is 3, but the description goes beyond by explaining what is retrieved (invoice summary + recent invoices), enriching the agent's understanding of what the uuid parameter targets beyond the schema's terse 'UUID of the supplier to retrieve.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get detailed information') with a specific resource ('a specific supplier'), and clarifies the scope: 'including invoice history summary and the last 10 recent incoming invoices.' It also notes that core data (name, CUI) comes from ANAF and is read-only, effectively distinguishing it from sibling tools like suppliers_list, suppliers_create, suppliers_update, and suppliers_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for retrieving a single supplier's detail view, contrasted implicitly with suppliers_list (retrieving multiple). It explains the scope (invoice history + recent invoices) and that core data is read-only from ANAF, giving the agent context on when to use it. However, it does not explicitly list exclusion conditions or name an alternative tool as a comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does well: discloses that the signing secret is returned only once and will be masked in subsequent responses, warns to store it securely immediately, and requires HTTPS for the URL. This is meaningful behavioral context beyond what the schema provides. Could add error behaviors, idempotency, or rate limits, but the critical behavioral warning is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all carrying meaningful content. The signing-secret warning is appropriately front-loaded. It's compact but information-dense. Loses a point only because it could be slightly tighter by trimming the redundant wildcard note already present in the schema, though it's arguably worth restating for emphasis.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 5 params (2 required), full schema coverage, and no output schema, this description covers the essential behavioral caveats: the one-time-only signing secret disclosure, HTTPS requirement, and wildcard subscription option. It's quite complete for a create action. Could mention that subsequent responses mask the secret or what the response contains, but the critical operational guidance is there.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by emphasizing the critical security behavior around the signing secret returned in the response (not a param but related context) and reiterating the ['*'] wildcard semantic from the events param. It also highlights the HTTPS requirement tying to the url param. This adds useful emphasis beyond the schema, though it doesn't cover isActive or companyId specifics in the description text itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb+resource ('Register a new webhook endpoint') and scopes it to 'the current company', distinguishing this from siblings like webhooks_list, webhooks_update, webhooks_delete, webhooks_get, and webhooks_test. The purpose is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear operational guidance: URL must use HTTPS, and how to subscribe to all event types via ['*']. It also explains the special signing-secret behavior. It doesn't explicitly state when to use this vs alternatives, but the create-vs-other verb distinction plus operational constraints give good context. No explicit exclusions or alternative references though.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the read-only nature (list), the admin-only restriction, the return granularity (one entry per platform ios/android/huawei), and the data semantics (YAML defaults, live DB override, merged effective values that drive /api/v1/version). This is meaningful behavioral context beyond a bare 'lists overrides'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly-scoped sentences with zero filler. Each clause carries information: role gate, per-platform granularity, data-source semantics, downstream API linkage, and companion tool reference. Well front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description compensates by explicitly enumerating return structure (one entry per platform, fields for YAML defaults, DB override, merged effective). It explains the merged values drive /api/v1/version. Given it's a zero-param read tool with no output schema, this is reasonably complete, though it could mention auth/permission failure behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has 0 parameters and 100% schema coverage (strictly, an empty schema). Description clarifies what the returned data means (YAML defaults vs live DB override vs merged effective values), which adds interpretive semantic value. Baseline 4 for a zero-param tool is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource: "List the per-platform version-gate overrides for the mobile app." Distinguishes from sibling admin_version_override_update clearly (list vs update). Clearly scoped to admin/mobile version-gate context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States SUPER_ADMIN only access requirement and notes the companion tool 'admin_version_override_update' for flipping the kill switch, providing clear context on when to use this read tool vs the mutation sibling. Lacks explicit when-not guidance but the role gate and companion-tool pointer are strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses a meaningful behavioral detail: the raw token value is never returned, only tokenPrefix for identification. This is genuinely useful transparency for a tool returning tokens, since the agent would otherwise expect full credentials. It also notes both active and revoked are returned, which affects how the agent interprets results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. Every clause carries information: the scope, the token statuses, the sort order, and the security detail about tokenPrefix. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with no output schema, the description is strong. It covers scope, content, ordering, and a critical behavioral detail (no raw token values). It could note whether pagination exists or clarify null behavior for empty results, but for this tool's complexity the current description is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema provides no information. The description compensates by describing the return characteristics (active and revoked tokens, sorted by creation date, tokenPrefix only). While it doesn't describe pagination or response structure, there being zero params means the baseline is 4 and the description adds value about what's returned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (list), the resource (API tokens), the scope (authenticated user within current organization), and specifies both active and revoked tokens included. It also notes the sort order (newest first). It distinguishes well from sibling tools like api_keys_scopes and anaf_tokens by being specific about returning both token statuses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what tokens are included (both active and revoked) and how they're sorted, which helps the agent know what to expect. However, it doesn't explicitly state when to use this vs alternatives like api_keys_scopes, nor does it mention any prerequisites like authentication requirements. Clear in context but no explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses key side effects: returns JWT access and refresh tokens, and stores them in session config for all subsequent requests. It also discloses the precedence condition (STORNO_TOKEN). It doesn't discuss failure behavior, rate limits, or what happens on invalid credentials, which prevents 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero padding. First sentence states verb, resource, mechanism, and side effect. Second sentence states the usage precondition. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an auth tool with 2 simple parameters and no output schema, the description adequately covers purpose, side effects, and usage ordering. It could mention failure behaviors or password security best practice, but for its complexity this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both email (with email format) and password clearly. The description adds token/session context but doesn't add syntax or security guidance beyond the schema. Baseline 3 is appropriate since the schema carries the parameter documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states the specific verb 'Authenticate' with the Storno.ro API using email/password, clearly explains the auth flow (JWT tokens, session storage). Distinguishes itself from auth_refresh and other auth_* siblings by its explicit role in establishing initial session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the precondition: 'Must be called before any other tool if STORNO_TOKEN is not set.' This gives clear conditional guidance on when to use this tool versus relying on a pre-existing token, effectively covering the when-to and when-not-to basis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses that both tokens are rotated, which is a critical behavioral trait (old tokens become invalid). It also states that new tokens are stored in session config, making the side effect transparent. This is meaningful behavioral context beyond what the schema conveys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero filler. Each sentence carries meaning: what it does, what rotates, where tokens go, and when to use it. No redundant phrasing or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, no-output-schema tool, the description is fairly complete. It covers the purpose, the rotation behavior, the storage side effect, and the usage trigger. The only minor gap is a warning that the supplied refreshToken may be expired/invalid and what error behavior to expect, but overall this is well-covered for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single optional parameter (refreshToken) that already has a description. The description adds marginal value by explaining rotation behavior, but the single parameter is well-documented in the schema. The baseline of 3 is elevated slightly because there's essentially nothing ambiguous to clarify with one optional param.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb+resource ('Refresh an expired JWT access token using the refresh token') with specific scope (access token refresh), including the rotation behavior. It's clear what this tool does and distinct from auth_login/auth_register which create tokens from scratch. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Use when the current token has expired,' which provides clear context for when to invoke this tool. It doesn't explicitly name alternatives or exclusions, but the auth_* sibling cluster (auth_login, auth_register, auth_me) makes the use case reasonably distinct. Could be strengthened by noting to use auth_login if no refresh token exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does excellent work exposing the openingBalance locking behavior (irreversible once set), the requirement to correct via cash movements thereafter, and the 'at least one field required' constraint. It also surfaces that IBAN must be valid and unique within company. The main gap is not disclosing the return/response format or any authorization requirements, but for the behavioral constraints that matter (mutability, locking), it is quite transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the purpose and scope, the second covers the crucial behavioral constraint, and the third states the minimum requirement. Every sentence earns its place with no fluff or repetition. It is appropriately sized for a tool with 9 parameters given the schema carries much of the parameter detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 9 parameters, 100% schema coverage, and no output schema, the description is quite complete. It explains the updateable fields, the critical lock behavior, the correction pathway, and the minimum-input requirement. The only gap is the lack of detail on what happens on success/failure (response format), but since there is no output schema and the tool is a straightforward update, the description covers the operation's semantics well enough for an agent to invoke it reasonably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds some value beyond the schema by explaining the locking semantics of openingBalance in prose, and noting the 'at least one field' requirement that isn't enforced by the schema. However, most parameter semantics (currency format, companyId override behavior) are already well-covered in the schema descriptions, so the description adds only modest incremental value here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (update), resource (existing bank account), and enumerates the specific updateable fields. It goes beyond a generic purpose by listing the exact attributes (type, IBAN, bank name, currency, default status, initial opening balance) and distinguishes the tool as an update operation for bank accounts, clearly differentiated from siblings like bank_accounts_create and bank_accounts_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage guidance: it explicitly states the lock behavior for openingBalance (once persisted > 0 it locks, corrections go via cash movements), which directly informs when NOT to use this tool for balance correction. It also states the 'at least one field must be provided' requirement, establishing a prerequisite. Though it doesn't name specific alternative tools, the openingBalance lock rule functionally directs users to cash register movement tools as the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It transparently discloses a key edge case: returns { configured: false } when no cash-type bank account exists or its opening balance is not set. This is valuable behavioral disclosure beyond what the schema shows. Minor gap: doesn't describe auth/permission requirements or whether this is a read-only operation (though 'snapshot' implies non-mutating).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, tightly packed with relevant information: what data is returned, plus the critical edge-case return value. No filler or redundant phrasing. Well-structured for a snapshot tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only snapshot tool with one optional parameter and no output schema, the description covers the core output fields and the main failure/configuration edge case. It's complete enough for an agent to select and invoke correctly, though a brief note on typical usage context (e.g., before closing the till) would strengthen it slightly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% but the parameter (companyId) is only lightly described ('Company UUID override (uses active company if not set)'). The description's main body doesn't add to the parameter, but given single optional parameter with clear schema description, minimal added semantics is acceptable. The description correctly scopes behavior to 'companyId' context implicitly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('live snapshot') with a clear resource ('the till') and enumerates exactly what data is returned (opening balance, cash in/out, manual movements, current balance). It distinguishes from the sibling cash_register_ledger and cash_register_movements_list by being the aggregate balance view rather than a transaction list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates when to use this tool: to view the current till state/balance rather than transaction history (ledger or movements list). However, it doesn't explicitly state when NOT to use it or name alternative tools for transaction-level detail, which sibling differentiation would require for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the key behavioral trait that this tool does NOT create a client (a read-only lookup), which is essential safety information. It also states it returns 'pre-filled form data' describing the output shape. While it doesn't disclose rate limits or network dependency on ANAF, the non-mutating nature is the most important behavioral fact and is clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero wasted words. The first sentence states purpose and the non-mutation behavior; the second describes the return value and its downstream use. Efficient and front-loaded with the most important information first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only lookup tool with 100% schema coverage and no output schema, the description is quite complete. It explains what it returns, what it doesn't do (create), and how results connect to a sibling tool (clients_create). The only minor gap is that it doesn't describe failure modes (e.g., what happens if CUI not found in ANAF), but for this simplicity level the description is solid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 meaning by explaining that the cui parameter identifies a company in the ANAF registry and that the returned data feeds into clients_create. The description of the returned fields (name, address, VAT status, registration number) provides context on what the cui lookup yields, adding value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Look up company details by CUI in the ANAF public registry without creating a client' with a specific verb (look up), resource (ANAF registry), and scope. It distinguishes itself from clients_create by explicitly noting it does NOT create a client and provides pre-filled form data, and from clients_vies_lookup and anaf_validate_cif by specifying the ANAF public registry context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states this is for lookup before creating a client ('without creating a client') and explicitly says the returned data 'can be used to populate a clients_create call,' which implies the use case of pre-populating client creation. However, it doesn't explicitly exclude alternatives like clients_vies_lookup or anaf_validate_cif, though the CUI/ANAF distinction is reasonably implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden. It explicitly states the asynchronous nature ('Submission is asynchronous — the status will update from uploaded to ok (with UIT) or nok (with error)'), which is valuable behavioral information the agent needs to know. It doesn't state error/retry behavior beyond 'nok (with error)' or auth requirements, but the async flow disclosure is substantive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, dense with necessary information: target system, prerequisites, async behavior, and outcome states. No filler or repetition of schema information. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only 2 params and good schema coverage, so the description doesn't need to carry much structural load. It explains the workflow context (submission, issued status, e-Transport fields) and the async result states. It could mention retry implications or specific error handling, but for a focused submission tool with good schema support and a clear status progression, the description is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 in the schema. The uuid parameter is clearly described ('UUID of the issued delivery note'). The description adds value by explaining the preconditions for the uuid-valued note (must be in issued status with e-Transport fields filled). The companyId parameter is self-explanatory in the schema ('overrides configured default'). Baseline 3 applies with full schema coverage, and the description's prerequisite context adds marginal value above that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (submit), resource (issued delivery note), target system (ANAF e-Transport), and purpose (domestic transport declaration TTN). It distinguishes from siblings like delivery_notes_issue, delivery_notes_validate_etransport, and anaf_sync_trigger by specifying this is the submission step specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states prerequisites ('delivery note must be in issued status with e-Transport fields filled: vehicle number, route, transport data, line tariff codes and weights'), giving clear context for when the tool is applicable. It doesn't explicitly state when NOT to use it or name alternatives, but the required precondition effectively guides the agent. The mention that submission is asynchronous is also helpful context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does an excellent job: states 'Permanently delete,' warns about referential integrity and audit trail implications, and explains the precondition (never used). The only gap is not describing the return value or error behavior, but the safety-critical constraints are well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero wasted words. Each sentence adds distinct value: the action, the constraint, and the recommended alternative. Front-loaded with the primary purpose and immediately follows with critical constraints. This is exemplary conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete operation with no output schema and no annotations, the description handles the critical context well: permanence, referential integrity, audit trail, and the never-used precondition. It could mention error behavior on attempting to delete a used series, but the core decision-relevant information is covered. Almost complete for this tool type.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (uuid and companyId) are documented in the schema itself. The description adds the meaning of uuid (the target series to delete) implicitly, but doesn't add significant new semantic detail beyond the schema's own descriptions. A baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool permanently deletes a document series, uses a specific verb (delete) plus resource (document series), and explicitly distinguishes it from alternative behaviors by stating it cannot delete used series and recommending marking as inactive instead. This differentiates it well from sibling tools like document_series_update, document_series_set_default, and document_series_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'Only delete if the series was created by mistake and never used.' It also explicitly identifies the alternative approach ('Consider marking as inactive (active=false) instead') and states the critical constraint (cannot delete series used for any documents). This is model guidance for use-vs-alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description does well: it explicitly states the file is single-use and auto-deleted after download, which is critical behavioral context. It also explains the filename provenance. The one gap is that it doesn't state whether the download response returns file bytes directly or requires a follow-up, and doesn't mention size/format constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all information-dense and non-redundant. Every sentence earns its place: purpose/mutability, filename provenance, and format examples. No filler or restating of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter download tool with full schema coverage, this description is nearly complete. It explains purpose, behavioral constraints (single-use, auto-delete), filename provenance, and common formats. It could mention response handling (binary stream vs. temp URL) but given the tool's simplicity and the presence of examples, it's adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter, and the schema already provides a description of the filename parameter plus an example. The tool description adds complementary context by explaining WHERE the filename comes from (the export generation endpoint) and giving concrete filename format examples. This goes slightly beyond the schema, though the schema already carries most of the meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb (Download), the resource (generated export file), and the format (ZIP archive). It specifies it's for generated export files, which distinguishes it from backup_download, invoices_pdf, and other download-style tools. The single-use and auto-delete behavior further clarifies the semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explains the filename comes from the export generation endpoint (e.g. POST /api/v1/invoices/export), which provides clear context on how to obtain the argument. It also gives example formats. However, it doesn't explicitly name sibling alternatives or state when NOT to use this tool, though the single-use framing strongly implies it's only for generated exports.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full disclosure burden. It clearly states the destructive effect (token immediately invalidated and cannot be used) and the limitation (cannot cancel accepted invitations). For a delete operation with no annotations, this is solid behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, zero waste. Covers purpose, immediate effect, and limitation without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter delete operation with no output schema, the description is adequate. It covers the intent, the destructive effect, and the boundary condition. It could optionally note whether the operation is idempotent or what happens when trying to cancel a nonexistent invitation, but for a single-parameter operation this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the uuid parameter already described as 'Invitation UUID to cancel.' The description reinforces that this is a cancellation of a pending invitation, adding the semantic context that the uuid refers to a pending invitation's token. The description adds some value by clarifying the token's lifecycle behavior, though the schema alone largely covers the parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear specific verb (cancel/delete) + resource (invitation). States the token is immediately invalidated, which distinguishes it from other invitation tools like invitations_list, invitations_create, and invitations_resend. The effect (invalidating the token) is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the tool is for pending invitations and explicitly notes it cannot cancel already-accepted invitations. However, it does not name the alternative for handling accepted invitations (which likely shouldn't be cancellable at all), nor does it distinguish when to use this vs invitations_resend. The context of 'cancel a pending invitation' is clear but no sibling exclusion is explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full disclosure burden. It discloses the status change to 'cancelled', that cancelled invoices remain in the system for record-keeping (non-destructive), and requires a cancellation reason with minimum length. This is good behavioral context for a mutation tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, information-dense sentences entirely focused on the tool's behavior and constraints. No filler or repetition of schema details. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-entity mutation with full schema coverage and no output schema, the description is complete. It covers the action, status change, retention behavior, undo path, and requirement for a reason. Minor gap: doesn't mention what happens if the invoice isn't in an issable state or if there are side effects, but given the simple schema and sibling differentiation this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters (uuid, reason, companyId) are fully documented by the schema. The description reinforces the reason minimum length requirement and adds the companyId context ('active company if not set' is in schema). The description adds the reason semantic (cancellation reason) which the schema already covers. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Cancel') with a clear resource ('an issued invoice'), and explicitly states the resulting status change to 'cancelled'. It distinguishes itself from the sibling invoices_restore, invoices_delete, and invoices_storno tools by clearly framing this as the logical cancellation action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use guidance and explicitly references the alternative invoices_restore to undo an accidental cancellation. It notes this only applies to 'issued invoices,' setting the scope. However, it doesn't contrast against invoices_delete or invoices_bulk_cancel for multi-cancel scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosure. It covers key behaviors: asynchronous sending via queue, PDF requiring Pro plan, optional attachments. However, it doesn't mention permissions needed, whether sending failure could occur, or audit/history visibility beyond what invoices_email_history implies. Generally transparent for an email-sending tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with zero waste. Front-loaded with the primary action, then workflow guidance, then behavioral notes. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters and no output schema, the description does a good job covering the essentials. It covers async behavior, plan requirements, attachment options, and the defaults workflow. Minor gap: doesn't mention the response/return value or what success/failure looks like asynchronously, which matters for an email-send tool with queue processing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all 10 parameters well. The description adds value by highlighting the relationship to invoices_email_defaults and noting defaults (PDF default true, XML default false) that affect parameter usage. The description reinforces the Pro plan requirement for attachPdf, beyond the schema's basic description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource+scope: 'Send an invoice via email with optional PDF and XML attachments.' It distinguishes from sibling tools like invoices_email_defaults (which pre-fills) and invoices_email_history, and from delivery_notes_email/receipts_email which are for different document types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use invoices_email_defaults first to get pre-filled subject/body, providing clear workflow context. Distinguishes the PDF attachment Pro plan requirement. However, it doesn't explicitly state when NOT to use this tool or name alternative tools beyond the defaults one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It transparently discloses the permanent/irreversible nature, downstream effects on invoice amountPaid/balance, and potential status changes to 'unpaid' or 'partially_paid'. This is strong behavioral context for a destructive mutation tool; only a minor gap is not describing the response/cascade beyond invoice side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, every phrase earns its place—what it does, the side effects, and an explicit irreversibility caution. Front-loaded with the primary action. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderate-complexity mutation tool (3 params, no output schema, no annotations), the description covers the necessary behavioral territory: action, irreversible side effects on the invoice, and the correction use-case. It could mention response/return expectations or permission requirements, but given the schema fully documents parameters, the description is arguably complete for typical deletion usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 3 params documented in schema). The description adds value by clarifying the paymentId comes 'from payments_list', and contextually explains that deleting a payment triggers invoice recomputation (explaining why invoiceId is needed). It reinforces the linkage between parameters and the described behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Permanently delete'), the resource ('a recorded payment from an invoice'), and the consequential effects (updates amountPaid, balance, and may change invoice status). It unambiguously distinguishes from the payment_create and payments_list siblings. This is a specific, well-scoped purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes clear it is for 'corrections' of recorded payments, and warns the action is irreversible. It implicitly contrasts with payments_create (creating) but does not explicitly name alternative tools or spell out when-not-to-use. The correction context and irreversibility warning give reasonable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly discloses the destructive nature ('permanently delete') and the audit trail implications of using the wrong method. It doesn't state whether there's any confirmation/undo, but 'permanently' signals irreversibility effectively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero wasted words. The first sentence states the action and constraint; the second provides the alternative path. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a destructive tool with no annotations and no output schema. The description covers the core lifecycle constraint (draft-only), the irreversibility ('permanently'), and the alternative for other states. It doesn't explain return values, but for a delete operation without an output schema this is a reasonable acceptance. It could note whether bulk deletion exists as a sibling, but that's implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (uuid and companyId) are already documented in the schema. The description adds minimal parameter-specific meaning beyond the state restriction on which proformas can be deleted. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Permanently delete a proforma invoice' with a specific verb (delete) and resource (proforma invoice). It also adds the critical scoping detail that only draft proforma invoices can be deleted, distinguishing this from the siblings proforma_invoices_cancel.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (draft proformas only) and provides an explicit alternative: 'Use cancel for sent/accepted/rejected proformas to preserve audit trail.' This directly names the alternative tool and the condition under which it should be used, which is excellent guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It clearly discloses the permanent/destructive nature ('Permanently delete'), the draft-only constraint, and the audit trail rationale. It doesn't mention auth requirements or what happens to related data, but the core destructive behavior is well disclosed. The absence of annotations means a 4 is earned by explicit disclosure of the key behavioral trait.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero waste, front-loaded with the primary action. Every word carries meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple delete operation with one required param and no output schema. The description covers the essential behavioral constraint (draft-only, permanent) fully. Some additional context about what happens to the receipt's associated data or audit entries could be added, but for a straightforward delete tool this is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters well documented ('UUID of the receipt to delete' and 'Company UUID'). The description adds no parameter detail beyond the schema, which is appropriate given full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Permanently delete a receipt' with a specific verb and resource, and distinguishes from siblings by noting the draft-only constraint versus cancel for issued receipts. This differentiates it well from receipts_cancel and the many other delete tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool ('Only draft receipts can be deleted') and when not to ('Use cancel for issued receipts to preserve the audit trail'), naming the alternative tool directly. This is exactly the kind of when/when-not/alternatives guidance the rubric rewards.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
This is a destructive operation (permanently delete) with no annotations provided, so the description carries the full burden. It discloses that the delete is permanent, that previously generated invoices are unaffected, and implicitly that this is irreversible (as opposed to the toggle). It could add more about permissions required or confirmation behaviors, but the key destructive aspects are well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the action, the non-destructive scope clarification, and the alternative usage guidance. No wasted words, no redundancy with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive single-resource delete tool with 100% schema coverage and a simple 2-parameter signature, the description is essentially complete. It addresses the key user concern (what happens to generated invoices) and the key alternative (toggle). Minor gaps could include return value info, but there's no output schema and the tool is straightforward enough that this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (uuid and companyId) documented in the schema itself. The description doesn't add semantic value to the parameters beyond what the schema provides, which is the baseline expectation when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (permanently delete), the resource (recurring invoice template), and the scope (a template, not generated invoices). It distinguishes itself from the toggling tools by noting previously generated invoices are not affected and offering an alternative. The purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly distinguishes this from the toggle tool ('Use toggle to temporarily pause instead'), providing clear guidance on when to use this destructive delete vs. a temporary pause. It also clarifies the scope of deletion (only the template, not previously generated invoices). This is strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It is a read-only retrieval tool and the description conveys this implicitly by being a 'get' operation. It discloses the tier semantics (blocking/recommended/ok/unknown), which tells the agent what kind of outcome values to expect. Does not explicitly state it's read-only/non-destructive, but the nature of a version-listing get tool makes this unambiguous, so a slight deduction from 5 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single well-structured sentence that front-loads the core purpose first, then elaborates parameter-driven behavior. Every clause adds useful information with zero filler or redundancy. Excellent economy of words while conveying the full contract.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a retrieval tool with only 2 optional, fully schema-documented parameters and no output schema, the description covers the key behavioral variations (payload shape per platform, version-driven tier resolution). It does not describe the exact structure of the returned objects, but with no output schema the description cannot fully enumerate this; given the tool's modest complexity and 100% schema coverage, this is near-complete. Minor gap: no mention of the full (omitted-platform) payload's exact shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description's job is to add value beyond schema. It explains that `version` 'Drives the gate.tier field' and is 'Only honoured when platform is also supplied,' adding interaction semantics not present in the schema. It explains `platform` returns a flat `client` object. However, since the schema already documents each parameter comprehensively, the added value is incremental rather than transformative, warranting baseline-3 rather than higher.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear specific verb+resource: 'Get backend version plus web and mobile latest+min versions and store URLs.' Distinguishes from siblings by describing the exact payload structure (backend version, per-platform web/mobile versions, store URLs). Contextually unique among a wide-ranging sibling set, clearly a version/health-info retrieval tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on when to supply `platform` (to get a flat `client` object) and when to add `version` (to get a resolved `gate.tier` instead of comparing yourself). Directly tells the agent it can pass `version` so it 'do[es] not have to compare versions yourself,' which is a strong usage directive. Clearly scoped vs sibling tools which handle different domains entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure and does well: it explains what soft-delete means (marked not physically removed), the reason (preserving historical invoice integrity), and two failure constraints. It effectively discloses that this is a non-destructive mutation despite the 'delete' name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero filler. Each sentence adds unique value: what soft-delete means, the constraints, and the impact on invoices. Exceptionally tight while still comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool operating on a single record with a clear effect, the description is quite complete. It covers semantics (soft vs hard), constraints (default and last-rate), and side effects (invoices untouched). No output schema exists, but the description's clarity about behavior compensates well for this simple mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does not add parameter-specific meaning beyond the schema, but the schema descriptions for uuid and companyId are already clear. The description's deletion constraints add context around which uuid values are valid targets, providing marginal added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (soft-delete) and resource (VAT rate), clearly distinguishing it from hard-delete operations. It explicitly differentiates itself from sibling tools like vat_rates_create and vat_rates_update by focusing on the deletion semantics. The soft-delete nature is a specific, distinguishing behavioral detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states constraints: cannot delete the default rate (set another as default first) and cannot delete the last remaining rate. It also clarifies scope (existing invoices not affected), giving the agent clear go/no-go criteria. This is better than most — it provides upfront 'do not call if' conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses a key behavioral trait — 'Only scopes the user already holds are returned' — which is important for the agent to avoid expecting all possible scopes. It also reveals grouping by category. This is genuinely useful behavioral context beyond what any schema would show.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. The first sentence states the core action and grouping; the second adds the scoping constraint and a usage rationale. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only list tool with no output schema, the description is complete. It covers what it lists, the grouping, the user-scoping filter, and a practical use case. There's nothing material left unexplained given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and the schema coverage is 100% (empty schema). Since there are no parameters to document, the baseline for a zero-param tool is 4. The description correctly focuses on the output semantics instead, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all permission scopes available to the current user, grouped by category' — specific verb (list), resource (permission scopes), and scope (available to current user). It distinguishes from the sibling oauth2_clients_scopes by noting both the grouping by category and the user-relative nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear use context — 'useful for inspecting what permissions a token can be granted' — telling the agent when it would be appropriate to call this tool. However, it doesn't explicitly state when NOT to use it or name alternatives (e.g., oauth2_clients_scopes for OAuth client scopes), so it's clear but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full transparency burden. It discloses immutability of prefix/type, semantics of active=false, and the risk of currentNumber changes causing duplicates. Slightly short of a 5 because it doesn't explicitly state a read-only/reversible nature for active changes beyond implication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all information-dense with no filler. Front-loaded with the primary purpose and immutability constraint first. Slight deduction: could tighten the duplicate warning, but content earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-param tool with no output schema and no annotations, the description covers mutation scope, immutability, deactivation use case, and duplicate risk. It doesn't explain return value or required permissions, but for an update tool with well-covered schema, it's reasonably complete. Minor gap: what happens to the series' associated documents when deactivated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already well documented. However, the description adds meaningful context beyond the schema: it clarifies that currentNumber affects the NEXT document number and that prefix/type are immutable even though they exist in sibling create tool. The description doesn't repeat schema info, adding contextual value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource ('Update an existing document series') with explicit scoping of what can and cannot change (only currentNumber and active; prefix and type immutable). Distinct from siblings like document_series_create, document_series_set_default, document_series_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states what fields are mutable vs immutable, gives concrete use case (active=false to deactivate at end of fiscal year), and warns against changing currentNumber to avoid duplicates. This is strong when-to/why-to guidance absent from schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden and does so excellently. It explicitly warns that the key is returned ONLY ONCE and must be stored immediately — a critical behavioral trait that could otherwise lead to data loss. It also discloses the permission restriction (owner-only) and the one-per-instance convention. This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with zero waste. Every sentence carries meaningful information: the action, the permission restriction, the critical one-time-return warning, and the one-per-instance guidance. Front-loaded with the core purpose, then critical caveats.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given it's a simple 1-param tool with full schema coverage and no output schema, the description is complete. It covers the essential operational concerns: permission context, the one-time-return hazard, and deployment guidance. A mid-complexity mutation tool with irrecoverable output is fully addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — the single parameter instanceName already has a clear description ('Human-readable name for the self-hosted instance e.g. Production, Staging'). The tool description doesn't add parameter-specific detail, but with full schema coverage and only one simple param, the baseline of 3 is appropriate. The description's one-per-instance note indirectly informs parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Generate a new license key') with a clear resource ('self-hosted Storno instance'). It clearly distinguishes from siblings like licensing_list_keys (listing) and licensing_revoke_key (revoking) by focusing on creation. The purpose is unambiguous and well-scoped.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides contextual guidance: only the organization owner can create keys, and each self-hosted instance should use its own key. While it doesn't explicitly name alternative tools, the 'each instance should use its own key' rule gives practical usage direction. It lacks an explicit 'use licensing_validate to test keys' pointer, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses important behavioral traits including that keys are returned with masked values (first and last 8 characters), includes both active and revoked keys, and that the operation is restricted to the organization owner. This is a safe read-like listing operation with meaningful disclosure of security/privacy behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the operation, the return format/masking behavior, and the access restriction. No fluff, no redundancy, tightly front-loaded with the core purpose stated first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple 0-parameter listing tool with no output schema. The description thoroughly explains what keys are returned (all, active and revoked), how values appear (masked), why they're useful (lastValidatedAt for verifying running instances), and who can call it (organization owner). For a listing tool this is complete; no output schema exists but the return behavior is well described for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100% (trivially, since there are no params). The baseline for 0 params is 4. The description doesn't need to explain any parameter semantics because there are none. The meaningful information about the return output (masked values, both states, timestamps) is a bonus contextual addition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb+resource+scope: 'List all license keys issued for the current organization.' It distinguishes itself from siblings like licensing_create_key, licensing_revoke_key, and licensing_validate by explicitly stating it lists keys, and contrasts well with the single-key operations. The scope ('current organization') is specific and useful.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when this is useful (to verify self-hosted instances are running via lastValidatedAt timestamps) and states the authorization requirement ('Only the organization owner can list keys'). It doesn't explicitly name alternative tools for listing or the when-not-to-use case, but the siblings (create/revoke/validate) provide natural contrast, and the use case stated is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does this excellently: explains this is a soft delete (key kept with active: false), discloses the 24-hour effect window on the instance, states irreversibility, and notes the owner-only restriction. This provides rich behavioral transparency beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient—four sentences pack in purpose, effect, irreversibility, and authorization. Every sentence earns its place with distinct information. Slightly verbose in places (e.g., the soft-delete explanation could be tighter) but overall well-structured and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema and no annotations, the description is thorough. It covers the purpose, side effects, irreversibility, authorization requirement, and timing of the effect. One small gap: it doesn't state what the response/return value looks like, but with no output schema and a simple id input, this is a minor omission rather than a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (the single 'id' parameter is described as 'UUID of the license key to revoke'). The description reinforces that the target is a license key, matching the schema. While the schema already covers the parameter well, the description adds the context that this is specifically a key that is currently active and will be deactivated, adding mild value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (revoke/deactivate) and resource (license key), explains the effect on the associated self-hosted instance, and distinguishes it from siblings like licensing_create_key and licensing_list_keys by focusing on the destructive deactivation action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the consequential behavior (fallback to Free plan within 24 hours), the irreversibility (revoked keys cannot be reactivated; generate a new key instead), and the authorization requirement (only the organization owner can revoke). It doesn't explicitly contrast with licensing_create_key as the alternative, but the irreversibility note implicitly guides the agent to prefer creating a new key over revoking when the goal is to reissue.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses key behaviors: the refund is auto-issued, linked back via refundOf, and inherits parent receipt series. It also states constraints (parent must be issued and not itself a refund). It doesn't explicitly mention side-effects like whether the parent's status changes or if payments get altered, but given the auto-issued/linked/inherits detail, it covers the most material behavioral aspects reasonably well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph that packs substantial information without waste. It front-loads the core action ('Issue a refund counter-receipt') then layers constraints and usage modes. Every sentence earns its place. It's slightly long and could arguably be broken into shorter sentences, but nothing is redundant or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with 100% schema coverage and no output schema, the description is complete. It explains the refund semantics (negative quantities, inverted payments), the linkage (refundOf), series inheritance, full vs partial refund modes, and quantity-exhaustion limits. Nothing critical appears missing for an agent to select and invoke this tool correctly. It doesn't explain return values, but no output schema exists so this is a minor gap at most.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already documents all 3 parameters well (uuid as parent receipt, companyId override, lineSelections with quantities). The description adds value beyond the schema by explaining the semantic difference between passing lineSelections (partial/lines-specific refund) versus omitting it (full refund of whole receipt), and notes that partial quantities are supported. This supplements the schema's mechanical descriptions with business semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: 'Issue a refund (counter-)receipt' that mirrors the parent receipt with negative quantities and inverted payment amounts. It specifies the resource (receipt), the action (refund), and the mechanism (counter-receipt with negative quantities). It distinguishes itself from sibling receipt tools like receipts_create, receipts_issue, receipts_cancel by describing the specific refund behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use context: 'Parent must be issued and not itself a refund.' It also explains the two usage modes clearly: omit lineSelections for full receipt refund, or pass it to refund only specific lines. It even discloses constraints like 'Multiple partial refunds against the same parent are allowed until the original quantities are exhausted,' which is strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosure. It does an excellent job explaining behavioral traits: the record is marked but not removed, existing invoices remain intact, and new ANAF-synced invoices trigger automatic restoration. This contextualizes the side effects and reversibility well beyond what a generic 'delete' would imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, all information-dense and zero waste. Each sentence provides distinct value: the operation type, the persistence state, the invoice preservation guarantee, and the auto-restoration behavior. Well-structured and front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter tool with no output schema, the description is remarkably complete. It covers the operation semantics, side effects, data preservation guarantees, and edge-case behavior (ANAF restoration). There is no output schema to explain, and the parameters are simple uuids fully covered by the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already well documented in the schema. The description doesn't add parameter-level detail beyond the schema, but with full coverage the baseline is 3; the description's contextual explanation about behavior on delete gives a small boost by clarifying what the uuid deletion actually accomplishes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (soft-delete), the resource (supplier record), and the critical scope detail that it is a soft delete, not permanent removal. It distinguishes from suppliers_bulk_delete and other delete tools by clarifying the soft-delete semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool versus alternatives by explaining it's a soft delete (not permanent), and notes that incoming invoices remain intact and restoration via ANAF sync can occur. It doesn't explicitly name alternative tools or state when NOT to use it, but the soft-delete vs. permanent-delete contrast provides clear context for choosing this over a bulk or permanent delete alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral burden and handles it well. It discloses the mutation behavior (creating a rate), the side effects (demoting existing default when isDefault=true, auto-default when first rate), and the category code semantics. This gives the agent a solid understanding of consequences before invoking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, then covers edge cases, then adds the reference table for category codes. Every sentence earns its place—no filler, no redundancy with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with a rich schema (100% coverage) and no output schema needing explanation, the description adequately covers purpose, side effects, default behaviors, and domain-specific category code meanings. This is complete for an agent to confidently invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all six parameters thoroughly. The description adds the category code mapping (S=standard, AA=reduced, etc.) and the isDefault behavioral consequences, which is genuinely useful context beyond the schema. Baseline 3 is appropriate since schema does most of the heavy lifting, but the category-code enrichment justifies not lowering it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new VAT rate for the active company' with a specific verb (create) and resource (VAT rate). It also explains the default-rate demotion behavior and first-rate auto-default, distinguishing it from sibling vat_rates_update and vat_rates_delete. The e-Factura category codes add domain-specific clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when this tool is appropriate (creating a new VAT rate) and covers edge cases (first rate becomes default, isDefault demotes existing defaults). While it doesn't explicitly name alternatives like vat_rates_update, the scope is clear enough given the sibling set, and the behavioral rules give good contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It clearly discloses the permanent/hard-delete nature with no recovery ('hard delete with no recovery'), which is the critical behavioral trait for a deletion tool. It doesn't describe return values or auth requirements, but the core destructive behavior is well communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences with zero waste. The first states the purpose and consequences, the second provides the alternative. Front-loaded with the most critical information (permanent deletion) at the start.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deletion tool with 100% schema coverage, this is complete. The irreversible nature is stated, an escape-hatch alternative is provided, and no output schema exists so nothing to document there. The complex destructive behavior is fully covered by the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both uuid and companyId params. The description adds no additional parameter-level detail beyond what the schema provides. Per the rubric, baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (delete), resource (webhook endpoint), and explicitly notes it permanently removes both the endpoint and its delivery history. It distinguishes from the sibling webhooks_update by noting that tool pauses deliveries temporarily, making the destructive nature unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (permanent delete) versus when NOT to use it (pause deliveries), and names the exact alternative (webhooks_update with isActive: false). This is model guidance comparable to the HIGH calibration example.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The description discloses that this is a read-only listing tool ('List all available webhook event types'), implicitly signaling a non-destructive operation. It adds structure information (categories and descriptions are included) that goes beyond the bare name. While it doesn't disclose pagination or size of the result, for a zero-parameter listing tool the behavioral profile is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. The first sentence states what it does and what it returns; the second gives the practical use-case. It is tightly written with no fluff or repetition, and the key purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple zero-parameter, no-output-schema reference/discovery tool. Given the minimal complexity and the absence of structured field documentation requirements, the description fully covers what an agent needs: what it returns (event types with descriptions and categories), the categories involved, and how to use the result (discover valid event names for webhook config). There is nothing substantive missing for the agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and the schema is empty. The description makes clear that no input is needed and that the output is a listing of event types with their descriptions and categories. Since there are no parameters to document, the baseline is 4 per the rubric. The description adequately conveys what the consumer receives and how to use that output downstream.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists available webhook event types with descriptions and categories. It names specific categories (invoices, payments, clients, sync, proforma) and explicitly states its purpose is to discover valid event names for webhook configuration. This distinguishes it from siblings like webhooks_list and webhooks_get, which manage actual webhook subscriptions, while this tool provides the vocabulary of valid event types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly frames when to use this tool: 'Use this to discover valid event names for webhook configuration.' This is clear contextual guidance that positions the tool as a discovery/reference tool preceding webhooks_create/webhooks_update. It doesn't state explicit negative cases (when NOT to use it), but the 'discover valid event names' framing makes the use case reasonably explicit. A sibling differentiation is implied but not explicitly named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the mutation state-flip behavior, the required COMPANY_EDIT permission, the specific failure case with its error code, and the return value shape ({ syncEnabled, message }). It doesn't describe idempotency or whether toggling off behaves differently, but for a toggle tool the coverage is strong. Small gap but well above average.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences packed with genuinely useful information: purpose, endpoint, permission, failure mode, return shape, and a recipe. Slightly dense in the second sentence with the HTTP details, but nothing is wasted and the info density is high without being bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a toggle operation this is remarkably complete: the purpose, mechanism, permission requirement, common failure mode with resolution path, return format, and a full enable recipe are all covered. The single required parameter is well documented in the schema. No output schema exists but the return shape is stated directly in the description. Nothing material is left unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (1 param, fully described as company UUID with instruction to use companies_list to find UUIDs). The description reinforces this by saying 'for a specific company' and references the UUID in the endpoint. Description adds the recipe context beyond raw schema but the schema already covers parameter semantics well, so a baseline-3-plus partial credit is fair.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool toggles ANAF SPV/e-Factura sync on/off for a specific company, with the exact endpoint (POST /api/v1/companies/{uuid}/toggle-sync) and the underlying effect (flips syncEnabled boolean). This is a specific verb+resource+outcome and clearly distinguishable from siblings like anaf_sync_trigger or anaf_sync_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance including the prerequisite: must connect via anaf_create_token_link first, and reveals the 422 ERR_SYNC_ENABLE_NO_TOKEN failure mode when no valid OAuth token exists. Also includes a complete step-by-step recipe (companies_list → anaf_create_token_link → anaf_validate_cif → companies_toggle_sync) for enabling on a fresh company, which is excellent usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides excellent behavioral disclosure: it always returns success to prevent user enumeration, only sends email if account exists, and the reset link is valid for 1 hour. This is precisely the kind of non-obvious behavioral context an agent needs. No annotations exist to contradict this, and the description fully carries the transparency burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero waste. Every sentence adds critical information: the action, the anti-enumeration behavior, and the token expiry. Information is front-loaded with the primary purpose first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, this is complete. The description covers the action, the security behavior, and the link validity. There is nothing ambiguous left for the agent to discover.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the single 'email' parameter is well-documented in the schema. The description adds meaningful context by explaining the behavioral contract (email only sent if account exists), which is more important than restating the parameter. Baseline 3 elevated due to the added behavioral semantics that help agent understand the parameter's significance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Request), resource (password reset email), and the purpose. It distinguishes itself from siblings like auth_login and auth_reset_password by establishing this is the email-sending step in the reset flow. The scope is precise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (to initiate a password reset) and differentiates from auth_reset_password (which likely consumes the reset token). It doesn't explicitly name the alternative tool, but the context around the reset flow is clear. No explicit exclusions stated, but the purpose is well-scoped enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the operation invalidates cached XML/PDF files so they regenerate with corrected data, which is valuable behavioral disclosure. It also clearly gates the operation to specific invoice states (not uploaded to ANAF, not cancelled), making side effects and prerequisites transparent. With no annotations provided, this description carries the full burden well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact but packs substantial information into two sentences: purpose, preconditions, behavioral side effect (cache invalidation), and the sibling alternative. Every clause earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 params (100% schema coverage), no output schema, and no nested objects, the description covers purpose, preconditions, side effects, and provides the batch alternative. It also explains what data gets updated (receiver name, CUI/CNP, buyer snapshot, VAT rules), making the scope clear. This is complete for the tool's complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning both uuid and companyId are documented in the schema itself. The description reinforces the uuid's role (invoice to resync) and the cache-invalidation implication. Per the baseline, 3 is appropriate when schema handles the heavy lifting, and the description provides matching context about what the resync updates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Resync a single invoice with its client's current profile data') and names the specific fields involved. It clearly distinguishes from the sibling clients_sync_invoices (batch version) by explicitly naming that alternative in the final sentence. Purpose is unambiguous and well-scoped.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage guidance: it explicitly states when the operation is NOT allowed (if uploaded to ANAF or cancelled), implicitly signaling when it IS allowed (unsent/rejected invoices). It also names the batch alternative clients_sync_invoices for resyncing multiple unsent invoices at once, giving the agent clear decision-making context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It does an excellent job: it states the old secret is 'immediately invalidated' (a destructive, irreversible side effect), that the new secret is returned 'once' (a one-time delivery constraint), and instructs to 'store it securely.' It also discloses the authentication limitation. For a security-sensitive mutation tool with zero annotations, this is exemplary behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, all essential. Each sentence carries distinct weight: what the tool does, the security implication of the response, and the destructive effect on the old secret plus the auth boundary. There is zero filler, no redundancy, and the most critical operational facts are front-loaded. This is appropriately compact for a simple one-parameter security tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description covers all essential aspects: purpose, return value behavior (new secret shown once), destructive side effect (old invalidated immediately), storage guidance, and authentication requirements. The existence of sibling oauth2_clients_revoke (which revokes rather than rotates) further clarifies the domain boundary. There's nothing material missing for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'uuid' is described in the schema as 'OAuth2 app UUID' with 100% coverage. The description doesn't add parameter-level detail beyond what the schema provides, but with only one parameter at full schema coverage, the baseline of 3 is appropriate. The description's reference to 'confidential OAuth2 application' adds some semantic context that helps interpret which UUID is expected, but doesn't dramatically exceed schema value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific, action-oriented language: 'Rotate the client secret of a confidential OAuth2 application.' It clearly identifies the verb (rotate), the resource (client secret of an OAuth2 app), and the scope (confidential applications specifically). It distinguishes itself from sibling tools like oauth2_clients_revoke and oauth2_clients_create because it addresses secret rotation specifically, which is a distinct operation not covered by any sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states a critical constraint: 'Cannot be called via API key or OAuth2 token.' This gives the agent crucial guidance about when this tool is usable and what auth context is required. While it doesn't name alternative tools explicitly, the requirement for app-level authentication is a clear usage boundary. It also implicitly communicates that this is for confidential (not public) OAuth2 applications, guiding appropriate selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden. It explicitly states that the previous secret is immediately invalidated, that the new secret is returned in full only in this single response (so it must be stored securely), and warns to update verification logic beforehand. These are exactly the behavioral traits an agent needs to know: irreversibility, one-time retrieval, and the operational prerequisite.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: what it does, the security-critical retrieval behavior, and the production warning. It is front-loaded with the primary action and efficiently conveys all necessary operational caveats without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema and no annotations, the description is remarkably complete for a security-sensitive mutation tool. It explains the action, the irreversibility, the one-time secret retrieval, and the prerequisite verification update. For a tool where the return value is the secret itself, the description adequately sets expectations without needing to detail a complex response structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents both parameters (uuid and companyId). The description doesn't add parameter-level detail beyond the schema, but it does contextualize the uuid by tying it to the webhook endpoint being rotated. With full schema coverage, baseline 3 is appropriate; the description adds no new semantic layer beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Issue) and the resource (a new HMAC-SHA256 signing secret for a webhook endpoint), and explicitly mentions the side effect of immediately invalidating the previous one. This is a specific and unambiguous action that distinguishes it from sibling webhook tools like webhooks_update or webhooks_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool — to rotate a webhook signing secret — and includes critical timing advice ('Update your endpoint verification logic before calling this in production'). This effectively tells the agent the operational context and cautions about production impact, which is strong usage guidance for a security-sensitive mutation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does this well by stating the cascade deletion scope (what gets destroyed: invoices, clients, products, ANAF tokens), the asynchronous nature of the deletion, role-based authorization requirements, and irreversibility. This is comprehensive disclosure for a destructive mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero filler. Every sentence carries essential information: what is deleted, the async cascade behavior, role restrictions, and irreversibility. Extremely dense and information-efficient without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even though there is no output schema, the tool is a delete action with a minimal input surface (one UUID). The description covers the key behavioral aspects an agent needs: what data is affected, expected latency (asynchronous), authorization requirements, and permanence. For a destructive tool, this is fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — the single 'uuid' parameter is described as 'Company UUID to delete'. The description adds marginal context by stating it's the company being permanently deleted, which reinforces the destructive nature but the schema already adequately documents the one parameter. With only one parameter and full schema coverage, the description need not add much here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool permanently deletes a company and all associated data (invoices, clients, products, ANAF tokens). It uses a specific verb+resource (delete company), and the scope of destruction is explicitly enumerated. It is clearly distinguishable from siblings like companies_set_active, companies_toggle_sync, and companies_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states role requirements ('Only Owner or Admin roles can delete companies') and emphasizes irreversibility ('This action cannot be undone'). It also notes the asynchronous cascade deletion behavior, which guides when and whether to invoke this tool. The warning about permanence serves as both a usage caveat and a when-not-to-use signal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the mutation side effects (audit-logged, in-app blocker ratchets instantly without redeploy), the permission requirement (SUPER_ADMIN only), and the per-field independence so an agent knows one field won't clobber others. This is rich behavioral context beyond what is in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Five tightly-packed sentences with zero filler. The most important information (what it does, permission, and the three-state semantics) is front-loaded in the first two sentences, with operational specifics following. Every sentence earns its place, including the concrete consequence of ratcheting minOverride.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter admin mutation tool with no output schema, the description covers permutations thoroughly: all field semantics, the notify flag's escalation context, the SUPER_ADMIN gate, audit logging, and the no-redeploy ratchet behavior. The multiple-value union types (null/string/object) are all addressed for each relevant field.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Though schema coverage is 100%, the description adds meaningful semantics beyond it: the three-state field behavior (override/clear/leave-as-is), the operational impact of bumping minOverride, and when notify should be passed true vs false. The example key format is in the schema but the description reinforces the critical override/clear/omit distinction that governs correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource+scope: 'Set or clear per-field version-gate overrides for one mobile platform.' This clearly distinguishes it from sibling admin tools like admin_version_overrides (a read/list) and admin_organizations/admin_users. It also specifies the permission level (SUPER_ADMIN only) and the per-field independence semantic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance including the three-state field semantic (set string to override, null to clear, omit to leave as-is), which is critical for correct usage. It also explains concrete operational scenarios: ratcheting the in-app blocker via minOverride, and the notify parameter behavior for fanning out to affected users. The 'Default off — pass true for ratchets, leave false for silent corrections' instructs clearly when to toggle notify.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![storno-cli MCP server](https://glama.ai/mcp/servers/stornoro/storno-cli/badges/card.svg)](https://glama.ai/mcp/servers/stornoro/storno-cli)

Score Badge

Copy to your README.md:

[![storno-cli MCP server](https://glama.ai/mcp/servers/stornoro/storno-cli/badges/score.svg)](https://glama.ai/mcp/servers/stornoro/storno-cli)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/stornoro/storno-cli'

If you have feedback or need assistance with the MCP directory API, please join our Discord server