Azquo

Write values with AQL

aql_write

Destructive

Write a 2D region of values into an Azquo database using the same AQL grammar as query_aql. AQL reference: https://www.azquo.com/connect/#aql

Mirrors the read shape — rowHeadings × columnHeadings × context — and adds a 2D values array. The cell at values[r][c] is anchored to the union of rowHeadings[r] + columnHeadings[c] + context, exactly as a read at the same coordinates would resolve.

Two modes, distinguished by options.createNames:

Case 1 — TRANSACTIONAL find-or-create. Caller supplies options.rowSet + options.rowLanguage (and/or columnSet + columnLanguage) + createNames: true. Unresolved row/column headings are FIND-OR-CREATED under the target set with the language attribute set. Arrow form: rowSet = "A->B" puts new names into B as a child of A (chain is auto-created if missing). Use for: importing new transactions, customers, or any entity whose ID column is the row heading.

Case 2 — MULTI-FACETED all-or-nothing (default; createNames: false). Every heading must resolve to an existing name. Any miss is fatal — no values land. Use for: writing into a pre-structured region where the names are already known.

Structure-only mode: omit values (or pass []). The call resolves the headings, find-or-creates names if createNames=true, but writes no values. Equivalent to declaring hierarchy.

For date columns where the duplicate-name trap applies, use options.rowLanguage = "date" (bare attribute name, no "language" prefix). rowLanguage / columnLanguage always take the literal attribute name verbatim.

createNames and ignoreHeadingErrors are mutually exclusive — supply at most one.

═══ PROVENANCE — required on every write ═══ source: origin reference (file/URL/document). Lands on Provenance.name in the audit trail. agent: your AI agent name (e.g. "Claude"). Lands on Provenance.method.

Input Schema

Name	Required	Description
`agent`	Yes	AI agent name (e.g. "Claude"). REQUIRED.
`source`	Yes	Origin reference — file, URL, document, or short note. REQUIRED.
`values`	No	2D array of cell values (string \| number \| boolean \| null). Omit or [] for structure-only mode.
`context`	Yes	Context expressions as a 2D array — use [[]] if no context needed
`options`	No	Engine options — see query_aql for the full shape. Adds rowSet/columnSet/createNames for AQL-write.
`business`	No	Optional. The business this call is for, by name, e.g. "azquo" - it then runs there whatever business the session is in. Worth giving on writes when you work in more than one business: a new MCP session starts in the login's own business. list_businesses shows the names.
`database`	Yes	Database name to write into
`rowHeadings`	Yes	Row heading expressions as a 2D array of strings
`columnHeadings`	Yes	Column heading expressions as a 2D array of strings

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 21, 2026

addedInput schema / properties / business

Added value: +{
+  "description": "Optional. The business this call is for, by name, e.g. \"azquo\" - it then runs there whatever business the session is in. Worth giving on writes when you work in more than one business: a new MCP session starts in the login's own business. list_businesses shows the names.",
+  "type": "string"
+}

First observedOct 19, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already declare destructive/non-idempotent/write, and the description adds real behavioral context: the all-or-nothing 'any miss is fatal — no values land' failure mode, find-or-create semantics, required provenance landing on Provenance.name/method in the audit trail. It does not state whether existing cell values are overwritten/replaced, which is a genuine gap for a destructive write.

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?

Long but appropriately so for a 9-param, two-mode, nested-option write tool. Core purpose is front-loaded, then modes, edge cases, and provenance are sectioned with headers and zero filler sentences.

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

Completeness4/5

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

For a complex mutation with no output schema it covers modes, failure semantics, mutual exclusions, and provenance thoroughly. The one omission is what a successful call returns (cells written, names created), which an agent would want without an output schema to consult.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (baseline 3), but the nested options object is only described as 'see query_aql for the full shape.' The description compensates with genuine semantics: createNames modes, rowSet/columnSet, the 'A->B' arrow form and auto-created chains, and the verbatim-attribute 'date' trap for rowLanguage/columnLanguage.

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?

Specific verb+resource+mechanism: 'Write a 2D region of values into an Azquo database using the same AQL grammar as query_aql.' It explicitly differentiates from the read sibling by naming query_aql and stating it mirrors its shape, so the agent can tell read from write without opening schemas.

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?

Explicit when-to-use routing: Case 1 (createNames:true) is flagged for 'importing new transactions, customers, or any entity whose ID column is the row heading'; Case 2 (default) for 'writing into a pre-structured region where the names are already known.' It also names the structure-only mode and the createNames/ignoreHeadingErrors mutual exclusion.

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

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