OpenAccountants

Answer a tax question (call first)

start

Read-onlyIdempotent

Call this first for any tax, VAT/GST, payroll or filing question about a country or US state, such as "how much tax will I pay in Spain", "do I need to register for VAT", "when is my tax return due", "is this deductible", "how is a freelancer or a company taxed in Germany", "sales tax in Texas" or "what changes if I move to Portugal". Pass the user's question as intent and the country or US state as jurisdiction ('DE', 'US-TX', 'Florida'). If no place is named, start infers one when the question makes it clear and says so in jurisdiction_source. Returns the skills to read next (skills_to_load, open each with get_skill), or what is still needed, usually the country. Covers 190+ jurisdictions; where no skill exists yet it returns a research_brief naming the official sources.

Input Schema

Name	Required	Description
`intent`	Yes	Required. The user's question or goal in their own words, e.g. 'how much tax will I pay as a freelancer', 'VAT return', 'set up a company'.
`reason`	No	One sentence, in the user's own words, on what they actually asked for here — captured only to improve routing. E.g. 'user sold ETH and wants to know what to report'. Optional but helpful.
`acting_as`	No	Optional. Who the user is: 'self' = a taxpayer handling their own taxes; 'client' = a professional working on a client's behalf. Infer it from the conversation; omit it if unclear.
`jurisdiction`	No	Country or US state: ISO 2-letter code, US state code or name (e.g. 'MT', 'GB', 'US-CA', 'Florida'). Omit if the user named none; start infers it when the question makes it clear.
`taxpayer_type`	No	The taxpayer's occupation, when known. Some return-prep workflows fork by it (an employee's Form 1040 is a different guide from a freelancer's). Pass it if the conversation already makes it clear; otherwise omit — start() only asks for it (status:'needs_clarification', needs:['taxpayer_type']) when the guides for this jurisdiction/intent genuinely split by occupation. 'employee' = W-2 wages only; 'self-employed' = freelance / 1099 / sole-proprietor; 'both' = employed AND self-employed; 'company' = a corporate entity. Don't guess — ask the user one short question if unsure.

Output Schema

Name	Required	Description	Default
`needs`	No
`intent`	No
`status`	No
`guardrails`	No
`next_action`	No
`expectations`	No
`jurisdiction`	No
`skills_to_load`	No
`available_intents`	No
`available_jurisdictions`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 9, 2026

changedInput schema / properties / acting_as / description

Previous value: -"REQUIRED. Who the user is: 'self' = a taxpayer handling their OWN taxes; 'client' = a professional (accountant/advisor) working on behalf of a CLIENT. Establish this before calling — if it isn't clear from the conversation, ask the user one short question ('Are these your own taxes, or are you helping a client?'). Never guess."New value: +"Optional. Who the user is: 'self' = a taxpayer handling their own taxes; 'client' = a professional working on a client's behalf. Infer it from the conversation; omit it if unclear."

changedInput schema / properties / intent / description

Previous value: -"User intent — REQUIRED. Free text, e.g. 'taxes', 'VAT return', 'set up a company'."New value: +"Required. The user's question or goal in their own words, e.g. 'how much tax will I pay as a freelancer', 'VAT return', 'set up a company'."

changedInput schema / properties / jurisdiction / description

Previous value: -"ISO 2-letter code or US state code (e.g. 'MT', 'GB', 'US-CA')."New value: +"Country or US state: ISO 2-letter code, US state code or name (e.g. 'MT', 'GB', 'US-CA', 'Florida'). Omit if the user named none; start infers it when the question makes it clear."

Changed1 schema field changedAug 26, 2026

changedInput schema / required

Previous value: -[
-  "intent",
-  "acting_as"
-]New value: +[
+  "intent"
+]

Changed1 schema field changedJul 14, 2026

addedInput schema / properties / taxpayer_type

Added value: +{
+  "description": "The taxpayer's occupation, when known. Some return-prep workflows fork by it (an employee's Form 1040 is a different guide from a freelancer's). Pass it if the conversation already makes it clear; otherwise omit — start() only asks for it (status:'needs_clarification', needs:['taxpayer_type']) when the guides for this jurisdiction/intent genuinely split by occupation. 'employee' = W-2 wages only; 'self-employed' = freelance / 1099 / sole-proprietor; 'both' = employed AND self-employed; 'company' = a corporate entity. Don't guess — ask the user one short question if unsure.",
+  "enum": [
+    "employee",
+    "self-employed",
+    "both",
+    "company",
+    "other"
+  ],
+  "type": "string"
+}

Changed1 schema field changedJul 13, 2026

addedInput schema / properties / reason

Added value: +{
+  "description": "One sentence, in the user's own words, on what they actually asked for here — captured only to improve routing. E.g. 'user sold ETH and wants to know what to report'. Optional but helpful.",
+  "type": "string"
+}

Changed2 schema fields changedJun 30, 2026

addedInput schema / properties / acting_as

Added value: +{
+  "description": "REQUIRED. Who the user is: 'self' = a taxpayer handling their OWN taxes; 'client' = a professional (accountant/advisor) working on behalf of a CLIENT. Establish this before calling — if it isn't clear from the conversation, ask the user one short question ('Are these your own taxes, or are you helping a client?'). Never guess.",
+  "enum": [
+    "self",
+    "client"
+  ],
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "intent"
-]New value: +[
+  "intent",
+  "acting_as"
+]

Changed1 schema field changedJun 18, 2026

changedOutput schema / properties / status / enum

Previous value: -[
-  "ready",
-  "needs_input",
-  "needs_clarification"
-]New value: +[
+  "ready",
+  "needs_input",
+  "needs_clarification",
+  "uncovered"
+]

Changed2 schema fields changedJun 2, 2026

changedInput schema / properties / intent / description

Previous value: -"User intent. Free text, e.g. 'taxes', 'VAT return', 'set up a company'."New value: +"User intent — REQUIRED. Free text, e.g. 'taxes', 'VAT return', 'set up a company'."

addedInput schema / required
```
Added value: +[
+  "intent"
+]
```

AddedMay 27, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the read-only/idempotent annotations, the description discloses non-obvious behavior: it may infer jurisdiction and report that via `jurisdiction_source`, it returns either `skills_to_load` or a clarifying request, and where no skill exists it returns a `research_brief` naming official sources. Coverage limits (190+ jurisdictions) and the fallback path are stated, which annotations alone would not convey.

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 action directive and the key parameters are front-loaded, and every sentence carries routing or behavioral information. It is on the long side because of the long example list of question phrasings, which is useful but slightly padded.

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 an entry-point router with an output schema, an optional-reason field and clarifying-question behavior, the description covers purpose, inputs, inference rules, next steps and fallback. Nothing an agent needs to invoke it correctly is missing.

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 real meaning: jurisdiction accepts ISO codes, US state codes or names ('DE', 'US-TX', 'Florida'), and it explains the inference rule for omitted jurisdiction. It also motivates taxpayer_type by the forking return-prep workflows, though the detailed field-level semantics live in 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?

The description names a specific action (route/answer a tax, VAT/GST, payroll or filing question) plus the resource and the scoping constraint ('about a country or US state'), and positions itself ahead of siblings by saying 'call this first'. An agent can distinguish it from get_skill, search_skills or list_jurisdictions without opening any schema.

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?

It states when to use it ('call this first for any tax... question'), names the concrete next step ('Returns the skills to read next (`skills_to_load`, open each with get_skill)'), and explains the alternative outcome when input is missing ('or what is still needed, usually the country'). Routing is explicit rather than inferred.

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

All OpenAccountants 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.