Azquo

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

Annotations cover the safety profile (idempotentHint, destructiveHint=false, readOnlyHint=false), and the description adds real side-effect detail beyond them: how idempotency actually behaves, that names get silently auto-created, and that source/agent land in an audit trail. It omits error modes and what happens with cycles or missing parents when createMissing=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and idempotency, then a compact Returns block, then a clearly delimited PROVENANCE section. Slightly dense in the returns enumeration, but every sentence carries information.

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

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

With no output schema, the description correctly supplies the return fields and their meaning. Provenance requirements for this write are spelled out. Missing only edge-case behavior (invalid parent with createMissing=false, error shape), which keeps it from full completeness.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds meaning the schema lacks — specifically that source and agent go into the audit trail and are mandatory on every write, which clarifies why they are required. It does not touch the business parameter, so it is not fully additive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Add parent → child relations between names'. It also names the sibling it hands off to (edit_name_attributes), so the agent can distinguish this hierarchy-building tool from attribute-editing tools without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operative context: idempotent behavior, the createMissing default that changes what gets written, and the follow-up workflow via namesResolved → edit_name_attributes. It stops short of explicit when-not-to-use guidance or naming alternative tools for overlapping goals.

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

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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnlyHint=true, so the 'Read-only' sentence is redundant, but the description adds real behavior: the query is re-run to locate the cell, provenance values are capped at 1000, a {message: "cell not found"} result for out-of-range row/col, and that overwritten values only surface while history_settings records history. Only permissions/auth context is unstated, so 4 rather than 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then call pattern, then return shape and edge cases — a sensible order. It is long and the 'Read-only' clause repeats the annotation, but nearly every sentence carries information an agent needs (call pattern, example, error case, history caveat).

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

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

No output schema exists, so the description carries the return contract itself (headline, function, auditForDisplayList with per-provenance fields) and covers the failure mode and history dependency. An agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema does not: rowHeadings/columnHeadings/context must be passed exactly as in the original query_aql call because the query is re-run, and it works through a concrete example (rows[2][0] = 1250 → row 2, col 0). The database param is merely implied by 'the same three arrays' framing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Explain where one value in a query_aql result came from', and enumerates exactly what it resolves (import, file, user or write, and when, plus the calculation). It also names the sibling it is not for, name_history, so an agent can separate the two without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit trigger ('Use it when a number looks wrong or the user asks "where does this figure come from?"') plus an explicit alternative and its condition ('For the history of a name's attributes and set membership use name_history instead'). This is the full when-to-use / when-not-to-use pattern.

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

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

Goes well beyond the annotations by naming exactly what is destroyed (a database already called by the target name is REPLACED and local edits are lost) and what auth situation applies (no key needed; the server uses the public read-only key). It also explains the idempotent/refresh semantics in user-facing terms. Note the mild tension with openWorldHint=false, since the copy is fetched from the remote host data.azquo.ai, but the endpoint is fixed and read-only, so this reads as an in-ecosystem fetch rather than a genuine contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the action and the source, then the mandatory user-confirmation step, then the destructive caveat. Dense but almost every sentence carries a distinct instruction; the refresh sentence and the key sentence are minor restatements but earn their place for a destructive, externally-sourced operation.

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

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

Covers purpose, safety, auth, refresh and the sibling lookup needed before calling, which is complete for a two-parameter tool with no output schema. The only gap is that it never hints at what a successful copy returns or how long it takes, which an agent might want given no output schema exists.

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

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

Schema description coverage is 100%, so both parameters (target and business) are already documented in the schema, making 3 the baseline. The description does add one useful cross-tool cue - use current_business to obtain the name for the confirmation question - but it does not explain the default or formatting of target beyond what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (copy), a specific resource (azquo_skills, glossed as the Azquo usage-skills database) and the exact source (data.azquo.ai into the current business). This is enough to separate it from siblings like copy_from_library or create_database 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use (local/offline Azquo needs its own copy), when-to-repeat (call again later to refresh), a required pre-condition (ask the user first and wait for a yes, with the exact confirmation wording), and a conditional check against list_databases when a same-named database already exists. Nothing is left to inference.

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

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false): it discloses that nothing is ever overwritten and that collisions become 'name_1', 'name_2', that names are sanitised (spaces to underscores, punctuation dropped), and that the returned `target` may differ from what the user asked for. These are exactly the mutation-side facts an agent needs before invoking.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, then the confirmation protocol, then behavior, then output guidance — every sentence carries distinct information. It is on the long side for a two-parameter tool, with a couple of clauses that could be tightened, but nothing is filler.

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

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

With no output schema, the description carries the burden of explaining the return value and it does so, telling the agent to report the `target` name from the result and why it may differ. Combined with the collision and sanitisation rules, an agent has everything needed to call this safely and report the outcome accurately.

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

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

Schema description coverage is already 100%, so the baseline is 3, but the description adds real meaning by tying values to sibling tools (list_library for valid database names, current_business to name the target business) and by explaining the naming/sanitisation semantics that determine what the stored name will be. It doesn't add format constraints for the `business` param itself, which is why it isn't a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Copy one database from the shared Azquo library into the current business') plus the payload that comes along with it (reports, import templates, uploaded file types). This clearly separates it from siblings like create_database, try_on_copy, and copy_azquo_skills without needing to open their schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when/when-not guidance: confirm 'Copy <database> into <business>?' with the user and wait for yes, and never copy speculatively or as a side effect of a browse request. It also routes the agent to the right sibling tools for each input (current_business for the target, list_library for the source names).

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

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

Adds substantial context beyond the annotations: role requirement, ownership effect, name-sanitization rules with a worked example, two named failure modes, and the default-server behavior. Annotations already cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, but the failure semantics go well beyond them. It stops short of saying whether creation is reversible or what happens to the caller's session context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Well front-loaded — purpose then alternatives then parameter notes then return value, in a predictable order. It runs long (~190 words) and repeats some name-cleaning detail already in the schema, but each paragraph carries usable information.

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

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

No output schema exists, and the description compensates by naming the returned fields (id, name, persistenceName, databaseServerId, zero counts) and suggesting next steps (apply_structure, import_file, persist_database). For a 3-parameter creation tool, 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.

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: databaseServerId is 'usually left out', resolves to the default the admin site offers first, and an unknown id fails with a listing of valid ids. The name-cleaning example ('Sales 2026!' becomes Sales_2026) also clarifies the transform beyond the schema's one-liner.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb + resource + scope ('Create a new, empty Azquo database in the current business') and immediately contrasts with the two relevant siblings, copy_from_library and try_on_copy. An agent can distinguish this from all 38 siblings without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use routing ('start a new model from scratch' vs 'ready-made one' vs 'experiment on an existing database'), plus a prerequisite (check list_databases first to avoid the create_failed collision) and a permissions condition (administrator or developer). Nothing is left to inference.

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

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

Annotations only declare the mutation/read hints; the description adds materially more: the link lasts 30 minutes, accepts any number of files, the server keeps the original plus a Markdown copy readable via read_document, the link itself is the only credential (no API key), and the sandbox network-access failure mode. This covers expiration, auth model, and side effects beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then the self-made-files branch and fallback. It is dense and long for a 4-param tool, with a few clauses that could be tightened, but nearly every sentence carries operational value (credential model, expiry, network caveat) so little is padding.

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

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

No output schema exists, and the description compensates by describing what the link returns (curlCommand), what the JSON reply contains (document ids), and the follow-up step (list_documents). Combined with the expiration and credential details, an agent has everything needed to call and act on this tool.

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

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

Schema coverage is 100%, so the schema documents all four params, giving a baseline of 3. The description goes further by explaining the effect of nameId (each upload appends a short DOCUMENT <id>/IMAGE <id> attribute and never stores the file in the name), which is semantics the schema does not convey. It does not elaborate on note or business beyond the schema wording.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: it produces a link where the USER uploads documents into Azquo. It also names the alternate flows (import_file/import_from_url are implied avoided routes) and immediately clarifies the return artifact (a link the user opens in a browser). An agent can distinguish this from sibling import tools without reading any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Use this whenever a file should be stored in Azquo - NEVER base64 a file into a tool call', plus a dedicated branch for self-made files (POST via curlCommand instead of re-upload) and a follow-up instruction (call list_documents afterwards). Both when-to-use cases and the exclusion (never base64) are stated.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful non-schema context — that the result is session-scoped and may include an acting-as override — but it does not explain what an acting-as override implies or what calling this changes (it changes nothing, which is worth stating).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, tightly written, with the return contents front-loaded and the usage instruction trailing. Every clause carries information and nothing is padded.

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

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

With no parameters and no output schema, the description carries the whole burden of describing what comes back, and it does so in prose (business, user, acting-as state). There is no missing prerequisite or return-shape ambiguity for an agent.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There is nothing for the description to disambiguate beyond the fact that the call requires no arguments.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a precise verb and three distinct return subjects (current business, current user, acting-as override state) scoped to 'this MCP session'. An agent can distinguish it immediately from siblings like list_businesses or switch_business, which enumerate or mutate businesses rather than report context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states an explicit triggering condition: 'Use before any destructive action.' That is concrete guidance. It falls short of 5 because it never names the alternative it complements (switch_business, apply_structure) or contrasts when to read context versus switch it.

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

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

Annotations already declare destructiveHint and non-reversibility, but the description adds cascading deletions (linked reports, import template if unused, upload history, pending uploads, source files) and what is kept, permission requirements (admin or owning developer), and the dangerous silent-refusal behavior that still returns {deleted: true}. This is rich context well beyond the 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the irreversible destructive nature, then proceeds in logically grouped blocks: alternatives, cascade effects, permissions, errors, return value. Despite the length, each sentence carries operational weight for a destructive, side-effecting tool.

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

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

Given a destructive, cascading operation with no output schema, the description covers permissions, error behavior, the silent-refusal trap, and even the return shape. Nothing an agent needs to call this safely is missing.

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

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

Schema coverage is 100%, so both parameters are already fully documented in the schema. The description reinforces exact-name matching and the business parameter, but adds little syntax or meaning beyond what the schema and its descriptions already provide — the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Permanently delete an Azquo database by name') and enumerates the full scope of what is removed. It explicitly differentiates from siblings delete_name and try_on_copy, so an agent can select correctly without opening other schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when/when-not guidance ('Do not call without the user explicitly asking... confirm the name and the business first') and names the alternatives (delete_name for a few names, try_on_copy for safe testing) with the condition that selects them.

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

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

Annotations already flag destructiveHint=true, but the description adds substantial context beyond them: irreversibility with no restore, deletion of the on-disk file, the authorization scope, the downstream effect that referencing databases keep pointing at a dead id and lose those rules, and the critical quirk that {deleted: true, id} is returned even when nothing was removed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the destructive warning, then prerequisites, side effects, and return caveat in a logical order. Every sentence carries information, though the return-value caveat and the database-pointer consequence make it longer than a typical tool description.

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

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

For a destructive mutation with no output schema, the description supplies the missing return-value semantics ({deleted: true, id}) including the false-success caveat, plus auth scope and side effects. Nothing an agent needs to call this safely is absent.

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

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

Schema description coverage is 100%, so both id and business are already documented in the schema. The description only restates that the id comes from list_import_templates and does not add format or edge-case detail beyond what the schema provides, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (delete) and resource (import template), and defines what the resource actually is: 'the workbook of rules that interprets incoming data files'. This distinguishes it cleanly from siblings like delete_database, delete_report and delete_name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when/when-not guidance: read first with read_workbook if the rules may be wanted, and 'Do not delete without the user asking for it.' It also names list_import_templates for obtaining the id and constrains usage to administrators in the current business.

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

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

Annotations declare destructiveHint=true, but the description goes well beyond them: it names exactly what is destroyed (values, uploaded documents and images, with the response's documentsDeleted count), states that those cannot be brought back, explains that the name itself can be restored as a NEW name via restore_name, and documents the 404 on a missing id plus the mandatory audit provenance.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the destructive effect and the recovery path, then the lookup mechanics, then a clearly headed provenance block. Every element earns its place, though the prose is somewhat long for a five-parameter tool.

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

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

No output schema exists, and the description compensates by describing the response field documentsDeleted and the 404 failure mode. Combined with the cascade/restore semantics and the required provenance fields, an agent has everything needed to invoke it correctly.

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

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 rationale the schema lacks: why nameId is an integer and where it comes from, and the audit-trail purpose of source/agent, including a concrete example for the agent name. It slightly duplicates schema text but reinforces the semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (delete a name) and immediately distinguishes its effect: values, documents and images uploaded via create_upload_link are destroyed while the name itself is recoverable. An agent can tell exactly what this does versus edit_name_attributes or restore_name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for use — look up by integer nameId sourced from apply_structure/describe_set/describe_query — and points to restore_name and list_deleted_names for recovery. It does not spell out an explicit when-not-to-use case, but no sibling performs the same deletion, so the guidance is effectively complete.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial context beyond them: the exact artifacts removed, irreversibility with no restore, that the underlying databases are untouched, the authorization requirement (administrator or the uploading developer), and the report_not_found error condition.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the destructive verb and scope before any caveats, and every sentence carries distinct information (irreversibility, read-first advice, consent requirement, blast-radius boundary, id sourcing, auth, error, return shape). Dense but nothing is wasted.

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

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

For a destructive, irreversible operation it supplies everything an agent needs: prerequisites from list_reports, authorization model, error behavior, blast radius relative to databases, and the return shape {deleted: true, id} in the absence of an output schema.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the business override and its rationale. The description only adds the sourcing hint for id from list_reports, which the schema already states. Baseline 3 is appropriate when the schema carries the parameter burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb (delete) plus a precisely scoped resource (one online report, defined as an Excel report users run in Azquo), with an enumeration of what is destroyed: workbook file, menu entries, external data requests, schedules. It also distinguishes itself from the sibling delete_name by noting the absence of any restore path.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when/when-not and alternatives: 'Do not delete without the user asking for it', read it first with read_workbook if the layout may be wanted, and contrasts with delete_name which can be restored. It also states where to obtain the id (list_reports).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description goes beyond that by enumerating the returned structure — sets, child counts, attributes, and the semantic meta-information subtree — which matters because there is no output schema to carry that information.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler. The return contents are front-loaded and the usage guidance follows, so an agent gets the payload description before the routing advice.

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

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

With no output schema, the description must and does sketch the return shape, and it frames the tool's role as an exploration entry point. It stops short of noting practical caveats such as subtree size at higher depth values or how the 'business' parameter interacts with a read, but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so depth, business, database, and attributes are all already documented in the schema, including the cross-business caveat on 'business'. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (get an overview) and resource (Azquo database) and then enumerates exactly what comes back: top-level sets with child counts, available attributes, and the meta-information subtree. This clearly separates it from siblings like list_databases and describe_set, which cover different scopes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Use this as the first step when exploring an unfamiliar database" gives an explicit entry condition, and "one call gives more context than multiple AQL probes" names the alternative (query_aql) it displaces. It lacks an explicit when-not-to-use clause, so it falls just short of the top mark.

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

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

Beyond the readOnlyHint annotation, it discloses that 'edit:...' commands and '... as <set>' assignments are refused because they mutate, that internal/user storage attributes are server-filtered, and that limit defaults to 50. These are concrete behavioral traits not present in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and return shape, then structured bullets for query syntax and behavioral notes. It is long, but for a query-language tool the syntax guidance and examples each earn their place; only minor trimming is possible.

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

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

No output schema exists, so the description correctly documents the return shape (parents, attributes, AI Text bodies, child counts, integer id). Combined with the syntax rules, write-refusal, attribute filtering, and default limit, an agent has everything needed to call and chain it.

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

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

Schema coverage is 100%, but the description goes well beyond it for the key 'query' param: postfix set-verb syntax, the backtick-quoting rule (including names containing 'as'), and set algebra operators (*, +, -) with examples. It adds little for 'business'/'database', so not a full 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (resolve) and resource (name-query expression) and enumerates the return payload: matched names with parents, attributes including AI Text bodies, and child counts. It explicitly distinguishes itself from sibling discovery tools (list_names, describe_set) and from the write path (aql_write, edit_name_attributes, delete_name).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use it: 'Use this after list_names / describe_set to read attribute values that the other discovery tools don't surface.' It also routes write commands to aql_write and explains how to chain the returned id into edit_name_attributes or delete_name, covering when-not and alternatives.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds meaningful behavioral context beyond that: it describes the return shape (child names with child counts, parent path) and explains the round-trip performance difference between a single combined call and 1 + N calls. It does not cover error handling, permissions, or size limits, but for a read-only tool with annotations this is solid added context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then usage context, then the advanced combined-call pattern. Every sentence contributes something useful: the return shape, the relationship to describe_database, the single-round-trip optimization, the alternative cost, and the final recommendation. It is appropriately sized for a tool with this much behavioral nuance.

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

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

There is no output schema, so the description must carry the burden of explaining return values; it does so by stating child names, child counts, and parent path, and by describing what the combined call returns (note bodies). It also covers the primary usage flow and the performance trade-off, leaving no critical gap for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The description adds meaning beyond the schema by explaining the interaction between depth and attributes (passing them together pulls a whole topic plus note bodies in one round-trip) and gives a concrete example (depth=2, attributes=["AI TEXT"]). It does not explain business or setName beyond the schema, but the key combined-parameter behavior is well covered.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Drill into a named set: returns its child names with child counts, plus the parent path.' It distinguishes itself from sibling tools by naming describe_database as a predecessor and describe_query as the alternative for per-child reads, so an agent can tell what this tool does and does not do without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says to use it after describe_database to explore a specific set, and it names describe_query as the alternative when depth/attributes are not passed. The guidance goes further by explaining the combined depth+attributes pattern for topic reads and instructing to 'Prefer the combined call for any topic-read,' giving clear when-to-use and when-not-to-use conditions.

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

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

Goes well beyond the annotations (destructiveHint=true, idempotentHint=true): it discloses that empty values delete attributes, that unmentioned attributes are left untouched (explicitly NOT wipe-and-replace), that a missing nameId yields 404 rather than a silent no-op, and that source/agent are required provenance landing in the audit trail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core semantics in the first two lines, then lookup behavior, then a clearly headed PROVENANCE block. Sections are separated and each sentence carries distinct information despite the overall length.

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

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

For a destructive write with no output schema, the description covers the mutation semantics, failure mode (404), partial-update guarantee, provenance requirements, and the rename path. Nothing an agent needs in order 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.

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: it explains the delete-on-empty-string semantics of the attributes map, the verbatim storage rule, the source/agent audit purpose, and where nameId comes from — context the schema fields do not carry.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Surgical attribute edit on an existing name') and immediately distinguishes itself from a wipe-and-replace sibling behavior. It also names related tools (apply_structure, describe_set, describe_query) as sources of the nameId, so an agent can place it in the workflow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides concrete when-to-use guidance, notably that renaming is done by setting default_display_name through this same call, and that the id comes from apply_structure/describe_* output. It does not, however, explicitly say when to prefer a different write tool (e.g. apply_structure or aql_write) over this one.

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

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

Annotations mark the tool as non-read-only and non-idempotent, but the description adds crucial side-effect details: choices are saved as the user's selections and affect future runs, empty string clears a saved choice, omitted choices persist, and invalid values restore saved choices. It also discloses one-use browserLink behavior, library read-only behavior, warnings for incomplete data, and specific error outcomes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but front-loaded and well structured: purpose first, then sibling alternatives, then parameter semantics, then behavioral caveats. Every section adds operational value for a complex report-runner, with no wasted filler.

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

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

Given no output schema and a complex tool that mutates saved choices, returns a browserLink, and has library and error behaviors, the description is complete enough for correct invocation. It covers return-adjacent context like browserLink, libraryCopy, validation failure, and render errors.

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

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

Schema description coverage is 100%, so the schema documents all four parameters in detail. The description reinforces required database, reportId as numeric ID or name, and choice key/value semantics, especially save/clear/omit behavior, but much of this is also present in the schema. Baseline 3 is appropriate because the schema does most of the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: fetches full report data including regions and current choices. It explicitly distinguishes this from sibling tools such as query_aql, read_workbook, list_reports, and open_in_browser, so an agent can select it 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use guidance and names alternatives with selection conditions: query_aql for ad-hoc questions, read_workbook for formulas/layout, list_reports to find reports. It also explains the special library-report path and read-only behavior.

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

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

Goes well beyond the annotations (destructiveHint=true, readOnlyHint=false): it states clear is NOT REVERSIBLE, requires confirm="CLEAR", requires an administrator or the owning developer, and requires provenance (source and agent). These are concrete operational requirements the annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then an efficiently formatted per-action list. It is fairly long, but nearly every line carries required operational detail (permissions, confirm token, provenance).

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

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

For a six-parameter destructive mutation tool with no output schema, the description covers everything an agent needs: action semantics, irreversibility, confirmation token, permission requirements, and provenance inputs.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the semantics of each action enum value and the role of confirm/source/agent for the write actions, though most of these are also mirrored in the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('See or change whether a database records history') and enumerates the four actions precisely. It clearly distinguishes itself from history-reading siblings like name_history and audit_cell, which query rather than configure.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use guidance per action: 'off' while a database is in development and every test import rewrites it, 'on' to start recording, 'clear' typically at end of development. It also states an explicit prohibition: 'Do not clear without the user explicitly asking for it.'

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

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

Annotations carry the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false), and the description adds hard behavioral context beyond them: a 256 KB decode cap that refuses larger input, the fact bytes transit the agent's context, and a concrete performance comparison. It does not say what the import does to existing data in the target database (merge vs overwrite), which is the one behavioral gap left 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the narrow-route warning and the cap before the alternative branches, and the bulleted alternatives are easy to scan. Slightly long, with the 256 KB limit repeated in both prose and schema, but every section carries routing or limit information.

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

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

Complete enough to call correctly: prerequisites, size cap, template selection, the optional `business` caveat, and escalation paths are all covered, and no output schema exists to require return documentation. The only omission is the effect on pre-existing data in the target database, relevant because the tool is flagged destructive.

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

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

Schema description coverage is 100%, so the schema already documents `business`, `database`, `filename` (template selection) and `fileContent` (base64, 256 KB cap). The description largely restates the filename-to-template and content-cap semantics rather than adding syntax or format detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Import SMALL INLINE DATA into an Azquo database') and immediately scopes it as the narrow route for base64 blobs under `fileContent`. It names the sibling it is not (the general route via import_from_url / HTTP), so an agent can distinguish it without opening the schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use ('ONLY when the data exists solely in your context and you have no shell') plus two when-not branches with named alternatives: fetchable-by-URL to import_from_url and shell-available to POST /api/importdata. It even quantifies the tradeoff (~0.1s vs minutes).

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

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

With annotations already declaring readOnlyHint=false, destructiveHint=true, and openWorldHint=true, the description adds substantial operational context: the server connects and fetches so rows never pass through context, credentials are held server-side and never supplied, the import follows the POST /api/importdata path, and the result should be checked for 'values adjusted'. This is well beyond what the annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and then structured into useful sections for connection behavior, source selection, and heading modes. It is longer than strictly necessary because it repeats some schema-level details for headings, but the organization is clear and most sentences carry useful operational information.

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

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

For a destructive, externally-connected import tool with six parameters and no output schema, the description covers the key context: data never enters the agent context, credentials are server-side, column meaning must come from either headings or an import template, and the result should be checked for 'values adjusted'. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so all six parameters, including business, database, filename, and headings, are already documented in the schema. The description restates the headings decision rule and connection lookup rather than adding new meaning, so the baseline 3 for high schema coverage is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: run SQL against an external database connection and import the result into an Azquo database. It explicitly distinguishes this from sibling import tools by saying it is the right choice for a business's own internal database, so an agent can tell what it does and when it applies without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit routing guidance: use list_external_connections to see configured sources, ask an administrator via azquo-admin if the source is missing rather than seeking another route. It also spells out the two headings strategies with when to use each (one-off load vs recurring feed) and points to list_import_templates for recurring feeds.

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

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

Goes well beyond the annotations: it discloses that the server performs the download, that the file name drives parsing of import instructions, that an Azquo header row is almost always required, and warns that a completed import is not proof of a correct one. For a destructive, non-idempotent write this is valuable extra context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core capability and the routing rule before the caveats. It is on the longer side, with a parenthetical aside about shells and MCP sessions, but nearly every sentence carries actionable information rather than filler.

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

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

Without an output schema, the description still characterizes the return (a validation summary with lines imported and values adjusted). Combined with the annotations covering safety and world-access, an agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100%, so the schema already carries the parameter detail; the description nonetheless adds conceptual meaning by stressing that the file name determines import instructions, which explains why filename and headings matter. It stops short of per-parameter guidance, keeping it just above the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Bulk-load a delimited-text or spreadsheet file into a database by URL') and immediately clarifies the mechanism (the server downloads it, not your context). It draws a clear line against the sibling import_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing rules: 'Use this instead of import_file for anything beyond a few KB,' plus a named fallback path (write to a file and POST /api/importdata, or fall back to import_file) for data that exists only in context. This is a genuine when/when-not decision tree.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds valuable behavioral context by explaining that entries are derived from the API key owner's email — one per business that email is a member of — clarifying the data scope and authorization basis.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences: purpose, derivation, and next-step alternative. Front-loaded with the core purpose, no waste.

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

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

For a parameterless read-only list tool with annotations covering safety and no output schema, the description is complete: it explains what is listed, the scope, and how to act on the result.

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

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

With zero parameters, the baseline is 4. The schema is empty, and the description needs no parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb 'List' and resource 'businesses', scopes it to 'this MCP session can switch between', and differentiates from switch_business by naming it as the tool for changing the active one. An agent can tell what this tool does and how it relates to siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context: use to see switchable businesses, and names switch_business for the next action. However, it does not explicitly state when not to use it or contrast with current_business for fetching the active business.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses important behavior: business sessions overlay azquo_skills and azquo_suggestions, overlaid entries carry overlay/readOnly/openWrite flags, library databases are read-only and carry library:true, and they are not listed in the user's business on admin.azquo.ai. This is rich context an agent needs to interpret results correctly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and then explains overlay and library semantics. It is somewhat long, but the additional sentences carry useful domain-specific information rather than filler.

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

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

With no output schema and one optional parameter, the description provides enough detail about return values by explaining the overlay, readOnly, openWrite, and library flags. It also explains the practical implication for library databases, which is important for correct follow-up behavior.

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

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

Schema description coverage is 100%, and the only parameter, business, is already documented in the schema with its semantics. The description does not add meaning beyond the schema, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: list Azquo databases available to the current user. It also explains overlay and local database distinctions, and ties library databases to related tools like describe_database, query_aql, and copy_from_library, so an agent can understand the tool's role among siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear post-listing guidance: library examples can be opened directly, and when a user works with a library database the agent should offer to copy it with copy_from_library after asking first. It does not explicitly state when not to use this tool or contrast it with every listing alternative, but the operational context is clear.

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

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

Annotations already mark this as read-only and not open-world, so the safety profile is clear. The description adds useful behavioral context: results are grouped into three kinds, counts per group are included, and empty groups are simply empty. It does not discuss permissions, but the annotations lower the burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and grouping, then moves to usage differentiation and return behavior. Every sentence adds value: the group definitions, the sibling comparison, and the note about counts and empty groups.

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

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

There is no output schema, but the description explains the return structure (three grouped categories, counts per group, empty groups when none). Combined with full schema coverage for parameters and annotations covering safety, the definition is complete for an agent to call this tool correctly.

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

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

Schema coverage is 100%, and the schema describes both the optional business parameter and the required database parameter. The description does not add any parameter syntax or usage details beyond what the schema already provides, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('List every Excel workbook associated with one database') and immediately clarifies the grouping into reports, setupSheets, and importTemplates. It also distinguishes itself from sibling tools by scoping to a single database, unlike list_reports and list_import_templates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit use case ('what spreadsheets come with this database?') and names the alternatives (list_reports, list_import_templates) while explaining the key difference: those are business-wide, this is scoped to one database. The agent can choose the right tool without further inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context: results are ordered most-recent-first, they carry who/when/child-count/set membership, and it discloses the important precondition that only history-recorded deletions appear. It doesn't cover pagination behavior despite a limit param.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four dense sentences that are front-loaded with what is returned, then filtering, then routing, then the precondition. Every sentence carries information, though the return-contents enumeration is slightly packed.

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

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

With no output schema, the description usefully enumerates the returned fields, states ordering, and gives the history-recording precondition an agent needs before calling. Combined with annotations covering the safety profile, this is nearly complete; only pagination/limit behavior is unaddressed.

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

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

Schema coverage is 100%, so all four parameters are already documented in the schema. The description restates parentId's narrowing behavior (which the schema also says) but adds nothing on limit or business. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('names that have been deleted') and immediately distinguishes itself from list_names by scoping to deletions, while also naming return contents and ordering. An agent can tell this apart from list_names without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Routes the agent forward explicitly: pass a returned id to name_history for last attributes or restore_name to restore it, which names the relevant siblings and their trigger conditions. It also states a usage precondition (only deletions made while history was recording are listed). It stops short of an explicit 'use this instead of list_names when...' contrast, keeping it at 4.

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

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

Goes well beyond readOnlyHint: discloses no paging (every document at once), null-handling for markdownChars with an accompanying markdownNote, the return envelope {database, count, documents}, and the database_not_found error condition including permission failure. This is exactly the behavioral context an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action and scope, then layers usage, exclusions, and return shape. Dense but every sentence is load-bearing; the parenthetical about markdownNote is slightly nested but justified.

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

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

With no output schema, the description carries the full burden and does so: it names the returned fields, the envelope, the count, and the error case. 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.

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning by explaining that nameId scopes results to one name's documents and how markdownChars/markdownNote relate to read_document output. It does not discuss the business parameter, but the schema documents it fully.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States the specific verb and resource (list the documents stored with a database), the ordering (newest first), the exact fields returned, and explicitly distinguishes documents from files loaded via import_file. The agent can separate it from read_document and import_file without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives two concrete use cases (find a document's id before read_document; see what source files back a database) and an explicit exclusion (import_file data is not listed here). It also names the nameId narrowing case, so both including and excluding conditions are covered.

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

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

Beyond the standard read-only annotation, the description adds two vital behavioral constraints: 'Credentials are never returned - the server holds them' (a security guarantee) and 'Connections are set up by an administrator in azquo-admin' (a constraint on data management/access). This significantly enhances operational awareness.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The tool definition is highly efficient. It presents the core function, followed by immediate operational instructions (usage), and then critical constraints (security/admin setup), making maximum use of minimal text.

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

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

The description is complete for a read-only listing tool. It details what the tool does, how its output must be used, and necessary security/administrative constraints, leaving no critical operational gaps for the agent.

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

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

Since the schema description coverage is 100%, the schema already fully documents the `business` parameter. The description provides contextual flavor ('for this business') but does not add semantic meaning that compensates for an incomplete schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description immediately states its purpose: to 'List the external database connections configured for this business.' Furthermore, it explicitly instructs the agent to 'Use the connection NAME with import_from_query,' clearly distinguishing its output role 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit instructions for workflow. It directs the user on the subsequent action required after listing the connection ('Use the connection NAME with import_from_query') and provides a critical contingency plan for missing connections ('ask for it to be added rather than looking for another route').

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, yet the description still adds genuinely new behavioral facts: empty array when the business has none and that results are not paginated. That pagination/empty-result disclosure is exactly the sort of thing annotations do not carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded, followed by definition, behavior, routing guidance, and return shape in a tight sequence. Each sentence carries distinct information with no filler or repetition.

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

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

With no output schema, the description compensates by enumerating returned fields (id, templateName, filename, notes, user, dateCreated) and edge cases (empty, unpaginated). Nothing needed to select or invoke this tool correctly is missing.

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

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

Schema description coverage is 100%, so the optional 'business' parameter is fully documented in the schema and the description need not repeat it. The description's phrase 'no parameters' is imprecise given that optional business argument exists, but it does not contradict any structured field; baseline 3 applies since the schema does the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('List every import template in the current business') and immediately defines what a template actually is, so an agent knows the domain concept rather than just the name. It explicitly distinguishes itself from list_database_sheets and read_workbook, which an agent could otherwise confuse with it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use: before import_file or import_from_query, and to find the id for delete_import_template. It also names the alternatives for adjacent needs (list_database_sheets for per-database templates, read_workbook to read rules), so the agent can route correctly without trial and error.

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

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

Annotations only declare readOnlyHint/openWorldHint, so the description carries the rest and does so: whole catalogue in one call with descriptions inline (no follow-up calls), exact row shape, and the important caveat that library databases are readable in place but do not appear in the user's business on admin.azquo.ai. That stealth-visibility trait is exactly the kind of behavior an agent cannot infer from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose and the payoff sentence first, then the row shape, then usage. Dense but largely waste-free; the closing copy_from_library sequence is slightly extended for a list tool, though it is genuinely actionable rather than filler.

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

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

With no output schema, the description enumerates the returned fields (name, sector, complexity, features, status, description, nameCount/valueCount when uploaded) and covers the read-in-place-plus-copy workflow. Nothing needed to call it or act on results is missing.

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

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

The single optional `business` parameter is fully documented in the schema (100% coverage, including its write-time relevance), so the baseline applies. The description never mentions the business parameter or its cross-business semantics, adding nothing beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Browse the shared Azquo library of example/demo databases") and immediately disambiguates from siblings by contrasting with the user's own business databases on admin.azquo.ai and with the absent search endpoint. An agent can tell this is a catalogue read, not a list_databases call.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit trigger cases ("Answer questions like 'is there an example with setup sheets?'"), explicitly rules out a search endpoint ("there is no separate search endpoint"), and prescribes the follow-up: offer copy_from_library early, copy only on an affirmative. Both when-to-use and when-to-act-next are spelled out.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds the non-obvious cap-ordering quirk: 'with a prefix match the cap applies before the prefix filter, so narrow the text if the result looks short.' It also discloses the return shape and that only current (not deleted) names are visible. The 'Read-only' sentence duplicates the annotation, but the cap semantics is genuinely valuable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose, then usage, then sibling routing, then parameter behavior and return shape. The Neighbours paragraph and example each earn their place, though the prose is denser than strictly necessary.

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

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

With no output schema, the description correctly fills the gap by describing the return array ({name, nameId, sets}) and the cardinality cap. Between the description and the fully-covered schema, an agent has everything needed to invoke this correctly.

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

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 value beyond the schema: the default behavior with neither filter ('names are returned unfiltered up to the cap'), the startsWith-wins precedence, and a concrete example invocation. It complements rather than repeats the parameter docs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource plus the matching mechanism: 'Find names in a database by text match on their display name.' It also explicitly distinguishes itself from siblings by naming describe_set, describe_query, and list_deleted_names and describing how each differs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-to-use condition ('when you know roughly what something is called but not where it sits') and a concrete workflow ('resolve an ambiguous label to the right nameId before querying or editing it'). The Neighbours paragraph routes the agent to the correct alternative tool for adjacent cases.

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

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

Although annotations already declare readOnlyHint=true, the description adds substantial behavioral context: role-based visibility, readOnly: true and library: true markers, duplicate reports across databases, placeholder behavior when none are visible, and that results are not paginated. It also warns against giving users plain report addresses because of the one-use signed-in link behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and usage, then organized into visibility and return-value details. It is lengthy, but most detail is relevant for this complex listing tool; the inaccurate 'no parameters' phrase is a small structural flaw.

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

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

With no output schema, the description usefully explains the returned array fields, role-dependent visibility, library overlay behavior, empty-result placeholder, and non-pagination. Its main gap is failing to mention the optional 'business' parameter and instead claiming there are no parameters.

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

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

Schema coverage is 100%, and the sole optional 'business' parameter is fully documented in the schema. However, the description says 'no parameters' and never mentions 'business', which is misleading for a cross-business tool even though the schema compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: list online reports the current user can see across every database. It explicitly distinguishes itself from list_database_sheets and positions itself before get_report_data, read_workbook, and delete_report.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance, including using the result to find a report id or name before calling get_report_data, read_workbook, or delete_report. It also names the alternative for reports/setup sheets/import templates of one database and explains how to show a report via open_in_browser.

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

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

Annotations only declare readOnlyHint/openWorldHint, but the description adds substantial behavior: role-dependent result visibility (administrator sees all, master sees only their created users, anyone else gets an empty list), that passwords are never returned, and that results are not paginated. The read-only restatement duplicates the annotation but the added context far outweighs it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then read-only confirmation, then usage, then visibility rules, then return shape. Every sentence carries decision-relevant information, including the field enumeration that substitutes for the missing output schema.

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

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

With no output schema, the description compensates by listing returned fields, their formats (status role values, yyyy-MM-dd endDate), and the absence of pagination. Permission-scoped visibility and the cross-session business caveat are also covered, so an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so the single optional 'business' parameter is already fully documented in the schema, including cross-references to list_businesses and switch_business. The description touches business scoping indirectly but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (List) and resource (user accounts of the current business) with the scope spelled out. It is immediately distinguishable from siblings like list_businesses, list_names, and current_business 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use cases (who has access and with what role, finding a user's email or team) and names the alternative for the session user (current_business instead). It also routes business switching to switch_business, leaving nothing to inference.

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

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

Annotations only cover readOnlyHint and openWorldHint, and the description adds substantial operational context beyond that: history is written at persist time so edits seconds old may not appear, history may be switched off or cleared so absence of entries does not mean absence of changes, and only attribute/set-membership changes are recorded. These are exactly the caveats an agent needs to interpret empty results correctly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the return payload, then parameters, then caveats, and every sentence carries information. It is somewhat long and occasionally packed, but there is no redundant or marketing filler to strip.

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

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

With no output schema, the description takes on the burden of describing return content in detail (versions, membership changes, last attributes, parents/children) and covers the failure modes (history disabled, persist lag). For a read-only five-parameter tool this is complete enough to call correctly and interpret results safely.

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

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 clarifies asAt semantics beyond the schema text by explaining that a bare date means 'the end of that day' and giving concrete format examples. It does not add anything for business or maxMembers, but those are already fully documented in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource (one name) and enumerates exactly what the tool returns: attribute-version history, membership-set changes, and last attributes/parents/children if deleted. It distinguishes itself from adjacent tools by explicitly scoping to attributes and membership and naming audit_cell for values, list_deleted_names for id lookup, and history_settings for configuration.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states when the tool applies ('works for deleted names too'), routes the agent to list_deleted_names for finding ids of deleted names, and points to audit_cell for value-level history and history_settings for whether history exists at all. Both the alternative and the condition selecting it are given, leaving nothing to inference.

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

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

Annotations only say this isn't a read-only/idempotent/destructive call; the description goes far beyond that. It discloses the single-use 10-minute expiry, the security implication that anyone holding an unused link is signed in as the person, and the limitation that library reports open read-only with non-functional executes — all things an agent cannot infer from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose and the security/expiry constraint early, then handles the library caveat and return values. It is dense rather than padded, though the layout is a run-on block and the 'choices ... as there' cross-reference is slightly terse.

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

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

Covers what the agent needs: return fields (url, expiresInMinutes, reportName), the error case mirroring get_report_data, the read-only library branch, and the confidentiality obligation. With no output schema, describing the returns and errors is exactly the right compensation.

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

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

Schema description coverage is 100%, so all four parameters including the nested choices object are already documented. The description only adds the ordering semantics that choices are applied before opening and that reportId/database behave as in get_report_data; useful but marginal against a fully documented schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (opens a report in the person's own browser) and immediately scopes it: it is the live, interactive report signed in as the user, not a data dump. It explicitly distinguishes itself from get_report_data, which is named as the sibling that returns figures instead.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit decision rule: use this when the person should see or work in the report, use get_report_data when they want figures in chat. It also covers the library-report variant (read-only, no Save, executes don't run) and tells the agent to communicate that to the person, plus a hard operational constraint that the agent must act immediately rather than cache the link.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds genuinely new context: writes live in an in-memory queue and this call is what makes them durable. It does not mention whether flushing with nothing pending is a no-op or an error, but the core behavioral model is disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no padding, with the core action front-loaded and the triggering tools in the supporting clause. Every sentence earns its place.

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

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

No output schema exists, and the annotations already carry the safety profile, so the description's job is to explain the in-memory queue model, which it does. Minor gaps remain around failure/no-op behavior when nothing is pending.

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

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

Schema description coverage is 100%, with 'database' documented and 'business' richly explained in the schema (including multi-business write guidance). The description adds nothing parameter-specific, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: flushing pending writes to disk for a named database. This is clearly distinguishable from siblings like apply_structure or aql_write, which produce the queued writes rather than persisting them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells the agent when to call it: after edits made via edit_name_attributes, apply_structure, and AQL edit primitives, which are queued in-memory. It names the producing tools and the durability goal, though it gives no explicit when-not-to-call case (e.g. no pending writes).

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

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

Beyond readOnlyHint=true and openWorldHint=false, the description discloses that write-like headings are refused, that unknown headings fail with aql_syntax unless ignoreHeadingErrors is set, that other failures return aql_runtime, and that rowLimit defaults to 1000 with truncation behavior. It also documents the response shape and pagination, which are not in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but front-loads the core purpose, constraints, and alternatives before moving into heading mechanics, an example, response format, and error behavior. Most sentences carry useful invocation or interpretation guidance, though the density could be trimmed slightly without losing information.

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

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

With no output schema and a complex, nested input model, the description compensates by explaining the response fields (rowHeadings, columnHeadings, context, rows, rowCount, columnCount, truncated) and pagination controls. Error behavior and sibling alternatives are also covered, making it complete enough to call the tool correctly.

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

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 substantial meaning about heading semantics: nested string arrays, earlier-line inheritance, and the requirement that the last row/column line be filled for data anchoring. It also clarifies options such as rowLimit behavior and ignoreHeadingErrors, though the schema already documents most option fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: "Query an Azquo database using AQL (Azquo Query Language)." It also differentiates from key siblings by naming aql_write, get_report_data, describe_set, describe_query, and audit_cell, so an agent can route correctly without opening every schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use this tool (ad-hoc numbers from a database) and when not to (edit: commands or "as" assignments are refused; use aql_write instead). It also names adjacent alternatives for reporting, exploration, and lineage, making the intended context clear.

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

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

Goes well beyond the readOnly annotation: discloses the 40000-character default page size, the truncation/continuation contract, that downloadUrl expires in 60 minutes, and that the agent must hand links to the user rather than fetch them. The image/no-Markdown fallback (markdownNote explains, only download link returned) is exactly the kind of edge case that prevents mis-invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences, front-loaded with the core behavior before pagination and link handling. Every clause carries operational information; nothing is restated from the title or annotations.

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

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

There is no output schema, so the description carries the return-value burden and does it: markdown body, truncated, nextOffset, downloadUrl, markdownUrl, markdownNote. An agent can read, paginate, and correctly handle the no-Markdown case without further discovery.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds the cross-parameter relationship the schema cannot express: offset should be set to the returned nextOffset when truncated. It also corroborates the default page size, though it leaves maxChars bounds to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Read a stored document ... as Markdown') plus the preserved structure (headings, lists, tables, slides, pages). It also points at list_documents as the source of the id, which cleanly separates it from the discovery sibling and from read_workbook.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when-to-use routing ('see list_documents' for the id) and, crucially, tells the agent how to continue an incomplete read: 'call again with offset = nextOffset' when 'truncated is true'. It does not explicitly contrast itself with read_workbook, but the stored-document scope is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds genuinely new behavioral context: formulas are shown in preference to computed values, it returns structure/text and never the file, and permissions differ (setup sheets/import templates are admin/developer only; reports follow caller report permissions). These are non-obvious traits the annotations do not carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core verb+resource, then the two modes, then the return/permission caveats. Dense but essentially every clause carries decision-relevant information; only minor trimming is possible.

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

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

With no output schema, the description carries the burden and does so well: it describes both return shapes (sheets + defined names with scope/target; or a sheet's cells with formulas). Combined with stated permissions and the read-only annotation, an agent has everything needed to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond it: the semantics of omitting `sheet` (returns shape) vs providing it (returns cells), and the note that az_ defined names ARE the model. It clarifies routing more than the schema fields alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Read inside one workbook') and an enumerated resource ('report', 'importTemplate', 'setupSheet'), and even distinguishes the two modes (with vs without `sheet`). An agent can tell it apart from sibling readers like read_document or get_report_data without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: 'use list_database_sheets to see what exists', 'start here' for the no-sheet mode, and 'use the admin's Download button if you want the actual file' as an out-of-band alternative. When-to-use for each mode is spelled out.

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

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

Goes well beyond the annotations: it discloses that the restored name gets a NEW id, that attributes return as they were at deletion, that set memberships and children are relinked only "where those still exist", that VALUES ARE NOT RESTORED, and that the response counts relinked vs. failed items. These are exactly the consequences an agent needs before mutating.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the restore semantics and the most important caveat (values not restored) before the provenance block. The provenance section partially duplicates the schema field descriptions and the box-drawing header is noisy, but overall it is dense rather than padded.

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

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

For a mutation tool with no output schema, it describes both side effects and the shape of the response (counts of what was relinked and what could not be), plus provenance traceability back to the old id. Nothing an agent needs to call this correctly is missing.

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

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: nameId is the pre-deletion id and is obtainable from list_deleted_names/name_history, and source/agent are framed as mandatory provenance on every write. The business parameter's semantics remain schema-only.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ("Bring back a deleted name") and immediately distinguishes itself from delete_name/edit_name_attributes by naming the sibling sources of the id. An agent can tell what this does and where the input comes from without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives the prerequisite for use (ids come from list_deleted_names or name_history) and states the required provenance fields for every write. It does not spell out when *not* to restore or compare against alternative recovery paths, so it stops short of full when/when-not routing.

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

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

Annotations only declare the mutation/idempotency profile; the description adds substantially more: the switch is session-local and does not affect other agents on the same key, new sessions may reopen the key owner's business (so check current_business before writing), and writes in the prior business are retained. This is exactly the extra context the annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and the session-scoping caveat, then the alternative and the constraint. Dense but nearly every sentence carries operational value; the trailing reference to persist_database and 'azquo_skills id 775' is mildly tangential.

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

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

For a state-mutating, no-output-schema tool, the description covers scope, side effects, prerequisites, the selection constraint, and the interaction with per-call business arguments. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds a genuine constraint the schema does not express: 'Provide exactly one of businessName, businessId, or userId' (the schema lists all three as optional with an empty required array). It also points at list_businesses as the source of valid values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Switch the active business') plus the precise scope of the effect ('for subsequent MCP tool calls in this session'). It implicitly separates itself from current_business (read) and list_businesses (discovery) by naming them as the other tools that don't take a business argument.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly gives the alternative path ('to run one call in another business without switching, give that call a business argument instead'), the prerequisite ('call list_businesses first if unsure'), and the exactly-one-of rule. An agent has everything needed to choose this tool or avoid it.

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

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

Goes well beyond the annotations, disclosing that all reads and writes redirect to an in-memory copy, results are prefixed 'TRIAL COPY of ...', nothing persists, copies idle 2 hours are server-discarded, and trials are session-scoped so other agents keep hitting the real database. These are exactly the behavioral facts an agent needs and none contradict the annotation flags.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core concept and organized into logical sentences, each carrying useful information. It is somewhat long for a three-action tool and has a minor typo ('bulk edit:,'), but nothing is wasted.

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

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

Covers memory implications (whole database in server memory, start warns on large databases), the 2-hour idle timeout, session scoping, the refusal list, and the result-format marker. With no output schema, the description still tells the agent what to expect back.

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

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: it explains what each action value does (start copies, discard returns, status lists trials) and that database is required for start and discard. It does not elaborate on the business parameter, keeping this just below a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Try changes on a throwaway copy of a database') and immediately frames how it differs from the write siblings like aql_write and apply_structure by making changes provisional. An agent can tell this apart from direct-write tools without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names when to use it ('a risky restructure, a bulk edit, or a first attempt at an unfamiliar write'), describes the discard-then-reapply workflow in place of a commit, and lists the tools that are refused while a trial is active. This is a complete when/when-not/alternatives picture.

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