AgenticBooks

Profit & loss report

get_pnl_report

Read-only

Generates a profit & loss report for an organisation over a date range, from events that have been classified and (where needed) human-approved. Returns revenue, cost of goods, operating expenses, payroll, tax, and FX gain/loss as integer cents, plus derived gross_profit_cents (revenue - cost of goods) and net_profit_cents (gross profit - operating expenses - payroll - tax). Expense fields are positive magnitudes; revenue is signed (refunds reduce it). Events still awaiting review are EXCLUDED from all lines and reported in unclassified_cents with a warning — if the warning is present, the report is incomplete until those events are approved via approve_classification. Use this for "how did we do in " questions; for a full current snapshot prefer get_financial_summary. MULTI-CURRENCY: FX conversion is not enabled yet, so when a period contains events in more than one currency the combined *_cents fields are null (a cross-currency sum would be meaningless) and the real figures are returned per currency in currency_breakdown, each a correct single-currency report.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`org_id`	No	Optional. Defaults to the organisation the authenticated API key is bound to, so you normally omit it and never need to ask the user for their organisation UUID. If provided, it must match the key’s org or the request is rejected.	0e91146d-511c-469f-bdee-5c867b26ae0d
`currency`	No	ISO 4217 reporting currency label, default USD. Used only as the label for a single-currency period; a multi-currency period ignores it and returns a per-currency breakdown instead (no FX conversion yet).	USD
`period_end`	Yes	End of the period, ISO 8601 date (YYYY-MM-DD), inclusive through end of day.
`period_start`	Yes	Start of the period, ISO 8601 date (YYYY-MM-DD), inclusive.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`period`	Yes
`warning`	No
`currency`	Yes
`tax_cents`	Yes
`event_count`	Yes
`generated_at`	Yes
`payroll_cents`	Yes
`revenue_cents`	Yes
`net_profit_cents`	Yes
`currency_breakdown`	No
`fx_gain_loss_cents`	Yes
`gross_profit_cents`	Yes
`unclassified_cents`	Yes
`cost_of_goods_cents`	Yes
`unrealized_fx_cents`	Yes
`operating_expense_cents`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 20, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already provide readOnlyHint=true, and the description adds substantial behavioral detail: exclusion of unclassified events with warning, multi-currency handling (null combined fields, per-currency breakdown), sign conventions, and derived profit fields. This goes well beyond the annotation.

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 long but every sentence conveys important information—purpose, exclusions, derived fields, usage alternative, and multi-currency edge case. It is well-structured with a clear MULTI-CURRENCY section, though slightly dense.

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 the tool's complexity (multi-currency, exclusions, derived metrics) and the presence of an output schema, the description is remarkably complete. It explains return fields, sign conventions, the unclassified_cents warning, and the multi-currency behavior. Nothing essential is missing.

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 well-documented. The description adds context like 'over a date range' and explains multi-currency behavior for currency, but this largely mirrors the schema's param descriptions. Baseline 3 is appropriate since the description doesn't significantly add 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?

Clearly states the tool generates a profit & loss report for an organisation over a date range, with specific metrics listed. It explicitly differentiates from get_financial_summary by noting it is for period-based questions versus a current snapshot.

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 usage guidance: 'Use this for "how did we do in <period>" questions; for a full current snapshot prefer get_financial_summary.' Also notes that unclassified events are excluded and approval via approve_classification may be needed, implying when to use after classification.

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

All AgenticBooks tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?