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

Annotations already mark the tool as read-only and open-world, and the description goes well beyond them by warning that SummaryRow totals must not be double-counted, that supplying only one date is rejected, and that currency comes from the organisation's own Xero settings. It also discloses that the financial year may not match the calendar year and explains how to derive date parameters from financialYear.

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 long but each sentence addresses a real failure mode, output nuance, or derivation rule, such as double-counting SummaryRows and deriving dates from financialYear. It is front-loaded with the core purpose and structured so that critical warnings are not buried.

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

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

With no output schema, the description carries the full burden of explaining the result shape, and it names columns, rows, section, rowType, currency, and financialYear. It also tells the agent which period label to state when relaying figures and how to avoid calendar-year assumptions, making it complete enough for correct invocation and interpretation.

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?

Parameter schema coverage is 100%, so the baseline is 3; the description adds value by explicitly stating the together-or-omit-both rule, the rejection of a single date, and the 'omit both for current calendar month' convention. It does not add new meaning for the organisation parameter beyond the schema's guidance, so 4 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 clearly identifies the resource as a Profit and Loss report from Xero for the current organisation and date range, and adds detail about the columns and rows returned. It does not explicitly contrast it with sibling report tools such as get_xero_balance_sheet, so it stops short of full sibling differentiation.

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

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

The description gives strong when-to-use context: it is a read-only report, requires paired dates or no dates, and explains the effect of omitting both dates. It does not name alternative tools or say 'use this instead of X', but the report name and read-only framing make the primary use case clear.

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