fawtar

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

Annotations only indicate non-read-only and non-destructive; the description adds the useful caveat that a generic insert does not perform invoice side effects. It does not go further into validation, ID generation, or returned values, so it provides moderate but not rich behavioral context.

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

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

The description is front-loaded: action and key caveat first, alternative second, resource enumeration last. The resource list is redundant with the schema enum but convenient; otherwise no sentence is wasted.

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

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

For a generic multi-resource create with no output schema, the description is nearly complete: it names all creatable resources, excludes invoices explicitly, and warns about absent invoicing side effects. It stops short of resource-specific data shape guidance or post-create behavior, but those may be intentionally delegated to per-resource catalogs.

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

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

With 50% schema coverage, the description repeats the resource enum in plain language and adds examples, but it does not explain per-resource field requirements for `data` beyond 'The record's fields.' The invoice exclusion is a meaningful semantic distinction for `resource`, but the description still relies on the schema for most parameter meaning.

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

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

The first sentence names the action (create) and the affected resources (customer, product, vendor, employee, asset, or other simple record), and the second explicitly carves out invoices with fawtar_create_invoice. This makes the tool's scope concrete and distinguishes it from its nearest sibling.

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

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

It states the key alternative, fawtar_create_invoice, and the condition for choosing it ('for invoices'), with concrete reasons (sequential number, VAT, QR, ledger posting). This is exactly the when-to-use vs when-not-to-use guidance an agent needs.

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

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

Annotations only mark this as non-read-only and non-destructive, so the description carries the full burden. It discloses that this is a real financial document, is irreversible, takes a sequential number, posts to the general ledger, and must be corrected via a credit note. This is exactly the kind of behavioral consequence an agent needs beyond annotations.

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

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

Three short paragraphs with no filler. The irreversible financial warning and usage instructions are front-loaded, and the parameter mapping guidance is tightly written.

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

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

For a financial mutation tool with no output schema, the description covers the core action, parameter decision rules, user confirmation step, and post-issuance correction path. An agent has enough safety-critical context to invoke the tool correctly.

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

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

With schema description coverage at only 14%, the description compensates for the most decision-critical parameters: taxTreatment maps to VAT registration status and type maps to simplified vs standard with a buyer VAT number requirement. Other parameters are largely self-explanatory or already described in the schema, so the remaining gaps are minor.

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

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

States a specific verb-resource pair ('Issue a tax or ordinary invoice') and clearly distinguishes itself from sibling get/list/vat tools by emphasizing real accounting effects: next sequential number, VAT computation, ZATCA QR code, and general ledger posting. The scope is unambiguous.

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

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

Provides explicit selection rules for taxTreatment and type, and instructs the agent to confirm amounts with the user before calling. It does not explicitly name alternative sibling tools or exclusion conditions, but the 'cannot be edited afterwards' warning strongly implies when to avoid direct use.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description goes beyond by disclosing that invoices return line items and a public share link, adding behavioral context that is not present in annotations.

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

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

Two short sentences. The primary action is front-loaded, and the invoice-specific addition is concise and valuable. No wasted words.

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

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

For a simple get-by-id tool, the description covers the essential behavior and the notable invoice extra. It does not mention return format or all resource specifics, but these are not necessary given the simplicity and the schema enum.

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

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

Schema description coverage is 50% (id has a description, resource has only an enum). The description does not elaborate on parameters, but the resource enum is self-explanatory. This falls at the baseline; no added value from the description, but no gap that breaks usage.

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

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

Description states a specific verb ('Fetch') and resource ('single record by id'), and adds a useful detail about invoices. It is clear even without explicitly naming siblings; the contrast with 'fawtar_list' is implicit but apparent.

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

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

The description conveys that this is for fetching one record by id, which implies when to use it. It does not explicitly mention alternatives or exclusions, but the context of sibling tools (create, list, etc.) makes the use case evident.

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

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

Annotations already mark it readOnly and non-destructive, and the description adds meaningful behavior: filter syntax, supported predicates, and the explicit warning that unsupported field predicates are silently ignored. It does not overclaim or contradict the read-only hint.

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

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

The long resource list is justified because all 27 enum values need disambiguation, and the bullet format is scannable. The filter rules are front-loaded before the catalog, and there is no obvious filler, though it is still a sizable wall of text.

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

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

For a 5-parameter tool with no output schema, the description covers resource selection, filter predicates, sorting, paging, and ignored-field behavior. Minor gaps remain around response shape and pagination metadata, but the required invocation details are present.

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

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

Schema coverage is 60%: sort, filters, and resource have descriptions, while page and limit only have schema constraints. The description compensates with a predicate list, filter example, and per-resource meaning for the enum, adding real selection value beyond the schema.

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

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

The description leads with a specific verb and resource scope: "List records from any Fawtar resource", then enumerates 27 supported resources with short definitions. This clearly separates it from siblings like fawtar_create and fawtar_get even before inspecting the schema.

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

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

The opening sentence gives clear context: use this when you need to list records with filtering, sorting, and paging rather than creating or fetching a single record. It does not explicitly name alternatives or state when not to use it, so it stops short of 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds return format and sorting, but it says 'Every unpaid issued invoice' while the schema has a default limit of 50, which could mislead an agent into thinking all are returned. It also does not clarify that the totals are computed over the returned set or all outstanding, leaving ambiguity. This is a transparency gap beyond what annotations cover.

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

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

Two sentences with no filler. The core purpose is front-loaded, and the 'who owes me money' framing adds immediate context without redundancy.

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

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

The description explains the returned data (unpaid invoices with balance, days overdue, sorted by due date, plus totals) but omits critical details about pagination (limit) and the overdueOnly filter. It also fails to clarify whether totals apply to just the returned page or all outstanding invoices. Since there is no output schema, the description carries the burden of return semantics, and it only partially does so.

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

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

Schema description coverage is 50% (overdueOnly has a description, limit does not). The description does not mention either parameter or how they affect results. It fails to compensate for the missing schema documentation, and the 'Every...' phrasing even conflicts with the limit parameter's existence.

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

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

The description states a specific resource (unpaid issued invoices) and outcome (remaining balance, days overdue, totals), and explicitly frames it as the answer to 'who owes me money'. It clearly differentiates from siblings like fawtar_list (general list) and fawtar_vat_summary (VAT-specific) by focusing on outstanding balances.

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

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

It directly instructs when to use this tool ('This is the answer to who owes me money without composing filters by hand'), giving a clear use case. It does not explicitly exclude alternatives, but the context makes the intended scenario unambiguous. A minor deduction for not naming alternatives or edge cases.

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

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

Annotations already mark the tool as read-only and non-destructive. The description adds meaningful behavior beyond that: it discloses that only recoverable input VAT is included and explicitly excludes non-recoverable expenses. This is useful domain-specific behavior not visible 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.

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

The description is a single well-front-loaded sentence that states the core outputs first, then adds the important exclusion rule. It contains only relevant information and no redundant elaboration.

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

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

Despite having no output schema, the description fully enumerates the returned figures and the exclusion behavior. The two date parameters are already documented in the schema, and the read-only safety is covered by annotations. Nothing essential is missing.

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

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

Schema description coverage is 100%, with from and to both documented as inclusive YYYY-MM-DD strings. The description only refers to a 'date range' and adds no extra parameter-level detail, 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.

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

The description names a precise resource ('VAT for a period') and the exact figures computed: output VAT on sales, input VAT on expenses, and net payable. This clearly separates it from sibling tools like list or get by specifying the summary nature of the result.

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

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

The description gives clear context: it is for a date range and provides the figures a VAT return is built from. It doesn't explicitly mention when not to use it or name an alternative tool, but the purpose is specific enough that an agent can infer appropriate usage.

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