AgenticBooks

Add a chart account

add_chart_account

Adds a new account to the org chart. You pick the TYPE and NAME; the system auto-assigns the next free code in that type's range (income 4xxx, cogs 5xxx, opex 6xxx, asset 1xxx, liability 2xxx, equity 3xxx), never reusing a retired code, and sets the correct P&L rollup. If QuickBooks is connected the account is provisioned there immediately (provisioning_status active); otherwise it is created locally and stays pending until the next QuickBooks connect. The account is usable for categorisation right away. actor_id is optional — it defaults to the organisation entity.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`name`	Yes	The account display name, e.g. "Travel & Meals".
`type`	Yes	The account type: income, cogs (cost of goods), opex (operating expense), asset, liability, or equity. Determines the code range and the P&L rollup.
`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
`reason`	Yes	Why this account is needed. Stored verbatim in the audit trail.
`actor_id`	No	Optional. Defaults to the organisation entity (correct for an org-scoped key). If provided, it must be an entity belonging to this organisation — arbitrary UUIDs are rejected, so the audit trail cannot be attributed to someone else.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`account`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 20, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint=false, no idempotency/destructive hints), the description discloses important behaviors: auto-assignment of the next free code with no reuse of retired codes, immediate usability, conditional QuickBooks provisioning with an active/pending status, and actor_id defaulting. This adds substantial operational context not visible in structured data.

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 information-dense but every sentence earns its place. It leads with the core action, then explains the auto-assignment behavior, QuickBooks integration, immediate usability, and optional actor_id. No filler or 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?

For a creation tool with 5 parameters and an output schema, the description covers the essential decision factors: how codes are chosen, how provisioning behaves, what defaults apply, and whether the account is usable immediately. Combined with the rich schema and output schema, an agent has everything needed to call 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%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the type-to-code-range mapping (income 4xxx, cogs 5xxx, etc.) and the automatic rollup behavior. It also reinforces actor_id/org_id defaults, though the schema already covers these.

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 and resource: 'Adds a new account to the org chart.' It clearly explains what the tool does and distinguishes it from sibling tools like rename_chart_account, set_chart_account_active, and list_chart_accounts by focusing on creation and automatic code assignment.

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 context for when this tool applies: creating a new account, with details about type-based code ranges, P&L rollup, and QuickBooks provisioning. It does not explicitly name alternatives or state when to avoid using it, but the purpose is sufficiently distinct from siblings that usage is well implied.

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?