Well

by io.github.WellApp-ai

Overview Discussions Admin

Get schema

well_get_schema

Read-only

Discover available data types and fields.

USAGE:

well_get_schema() → List ALL available roots, including the accounting graph (ledger_accounts, journals, journal_entries) plus account_balances, tax_rates, exchange_rates — query these for real financial statements (compte de résultat / balance sheet) instead of reconstructing them from raw invoices
well_get_schema({ root: "invoices" }) → List all available fields for invoices

WORKFLOW:

Call well_get_schema(root) to see available fields
Pick the fields you need for your task (typically 5-15)
Call well_query_records with those specific fields

Returns fields with path, type, and (when documented) semantic context:

{ path: "invoices.grand_total", type: "numeric", context: "Total invoice amount incl. tax in the document currency...", enrichment: "AI extraction" } → use _eq, _gt, _lt, etc.
{ path: "invoices.local_currency", type: "enum" } → use ONLY _eq, _neq, _in, _nin, _is_null
{ path: "invoices.issuer.name", type: "text" } → use _eq, _like, _ilike, etc.
"context" (when present) explains what the field MEANS in the domain and how it's used — read it to pick the right field and write correct filters.
"enrichment" (when present) is the value's provenance (e.g. "Bank sync", "AI extraction", "System generated", "Derived", "Manual"). Use the type to choose the right whereClause operators in well_query_records. To use in well_query_records, convert path to array: "invoices.issuer.name" → ["invoices", "issuer", "name"]

Input Schema

TableJSON Schema

Name	Required	Description
`root`	No	Entity root to inspect. Omit to list every available root (call well_get_schema() with no argument first). Includes the accounting graph (ledger_accounts, journals, journal_entries) alongside companies, invoices, transactions, accounts, and more.
`depth`	No	Relationship depth: 0=scalars only, 1=direct relations (default), 2=nested, 3=level-3 graph
`workspace_id`	No	Target workspace. Optional: this tool describes the token itself rather than one workspace's data, so omitting it returns the same answer.
`conversation_id`	No	The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation.

Output Schema

TableJSON Schema

Name	Required	Description
`root`	No
`error`	No
`roots`	No
`total`	No
`fields`	No
`success`	Yes
`conversation_id`	No	The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.
`conversation_id_note`	No	Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.
`conversation_id_source`	No	Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedSep 22, 2026

addedInput schema / properties / conversation_id

Added value: +{
+  "description": "The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation.",
+  "type": "string"
+}

addedOutput schema / properties / conversation_id

Added value: +{
+  "description": "The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.",
+  "type": "string"
+}

addedOutput schema / properties / conversation_id_note

Added value: +{
+  "description": "Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.",
+  "type": "string"
+}

addedOutput schema / properties / conversation_id_source

Added value: +{
+  "description": "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened.",
+  "enum": [
+    "host_meta",
+    "argument",
+    "minted"
+  ],
+  "type": "string"
+}

Changed1 schema field changedAug 31, 2026

changedInput schema / properties / workspace_id / description

Previous value: -"Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than one workspace."New value: +"Target workspace. Optional: this tool describes the token itself rather than one workspace's data, so omitting it returns the same answer."

First observedJul 27, 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 destructiveHint=false. The description adds real behavioral context beyond that: the shape of returned entries (path, type, context, enrichment), how field type constrains whereClause operators, and that workspace_id is optional because this tool describes the token itself rather than a workspace's data. This materially enriches what the annotations alone 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 description is longer than average, but it is well organized into USAGE, WORKFLOW, and return-format sections with front-loaded purpose. A small amount of repetition exists around operator guidance and path conversion, but each major block earns its place.

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 introspection tool with an output schema, 100% parameter coverage, and safe read-only annotations, the description is complete: it covers invocation patterns, a canonical example, the expected workflow before querying, and the meaning of returned fields. Nothing needed to call 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?

Since schema coverage is 100%, the baseline is 3, and the schema already documents root, depth, workspace_id, and conversation_id. The description adds value beyond the schema by explaining operator rules per type (enum uses ONLY _eq, _neq, _in, _nin, _is_null) and by giving the path-to-array conversion rule for well_query_records. That lifts it above baseline.

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 first line, 'Discover available data types and fields,' states a specific verb and resource. The usage examples clearly distinguish the no-argument call (list all roots) from the root-specific call (list fields), and the workflow explicitly routes the agent onward to well_query_records, making the introspection role unmistakable relative to sibling tools.

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 explicit call order: call well_get_schema() first to see roots, then with a root to see fields, and then call well_query_records. It also calls out the accounting-graph roots for financial statements. It does not explicitly discuss when not to use this tool versus well_get_entity or well_get_graph, so it stops short of the highest bar.

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

All Well 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?