get_vat_liability_summary

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

The description goes far beyond the readOnlyHint annotation, disclosing how ledgers are classified (input/output/rcm/other), how matches are detected (structural vs name_pattern), that both signals are used together, that no parent group filter is applied, how netTotal is computed, and the special no-match behavior returning an explicit note instead of zero. This is exceptionally transparent about the tool's behavior and limitations.

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

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

The description is front-loaded with the core purpose and contains genuinely useful behavioral detail, but it is verbose and delivered as one long run-on paragraph. Points like the live-confirmed recall issue and the real-company group scattering are repeated across multiple clauses, which could be consolidated. No structure such as bullets or separate sentences for output shape versus matching behavior is used.

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 explains what each row represents, how rows are classified and tagged, how netTotal is computed, what happens when no ledgers are found, and why this is not Tally's canned VAT report. For a read-only two-parameter report tool, this fully equips an agent to select and 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?

The input schema fully documents both parameters (from and to) with date format descriptions, so schema coverage is 100%. The description adds 'for a date range' and confirms the period-based query, but it does not add significant new semantic detail beyond what the schema already provides. Since the schema carries the parameter documentation burden, a 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 opens with a specific verb and resource: 'Get a UAE VAT liability summary for a date range.' It clearly identifies the output as reconstructed ledger-based VAT liability, not Tally's canned report, and distinguishes the report type from sibling tools like get_gst_liability_summary through the explicit UAE VAT framing.

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 intended use is clear: call this when a UAE VAT liability summary for a date range is needed. It also provides useful when-not context by ruling out Tally's canned VAT return report and noting that the report is reconstructed from ledger balances like get_profit_and_loss. However, it does not explicitly name alternatives such as get_gst_liability_summary or state conditions for choosing one over another.

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