Azquo

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

With no annotations present, the description carries the full behavioral burden and does so well: it declares idempotency ('existing links stay; new ones are added'), the default auto-creation behavior, and enumerates every return field (applied, alreadyLinked, namesCreated, namesResolved) with the ordering of the resolved ids. It also flags the required provenance fields as 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 action, followed by idempotency, then returns, all clearly sectioned with a header for provenance. It is efficient overall, though the returns sentence is dense and the provenance block partially restates the 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?

For a write tool with no annotations and no output schema, the description supplies exactly what is otherwise missing: mutation semantics, idempotency, default behavior, full return-value explanation, and required provenance. Nothing an agent needs to invoke it correctly 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 coverage is 100%, so the baseline is 3, but the description adds real semantic value on top of it: it spells out the createMissing default, explains that source/agent feed the audit trail, and clarifies the chaining role of resolved ids. The only gap is a lack of detail on how invalid or cyclic relations are handled.

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'), which is unambiguous and distinguishable from write siblings like edit_name_attributes or create_database. It even names edit_name_attributes as the natural chaining target, orienting the agent within the tool graph.

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 idempotency rule and createMissing default give useful context, and the chaining hint ('use to chain into edit_name_attributes') implies a workflow. However, there is no explicit when-to-use vs. when-not guidance and no named alternative for callers who want different structural edits, so usage is only implied.

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 no annotations, the description carries the full burden and does well: all-or-nothing vs find-or-create semantics, fatal-on-miss behavior, chain auto-creation for arrow form, no-values structure-only behavior, and mandatory provenance fields with where they land in the audit trail. It stops short of saying whether an existing cell value is overwritten by a write, and says nothing about permissions or rate limits.

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 structured into labeled cases, a structure-only note, and a provenance block, with the core 'what it does' statement front-loaded. The '═══ PROVENANCE' banner is light ornamentation, and length is justified by the tool's two-mode complexity, though it could be trimmed slightly.

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 an 8-parameter, 6-required, nested-object mutation tool with no annotations and no output schema, the description covers mode selection, error semantics, and required provenance well. It does not describe what the call returns on success or the shape of a partial failure report, which nothing else supplies 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: options.rowSet/columnSet arrow form ('A->B'), that rowLanguage/columnLanguage take the literal attribute name with no 'language' prefix, that options is a write extension of the query_aql shape, and that a missing/empty values array toggles structure-only mode. This is semantics well beyond the schema text.

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 (write) and resource (a 2D region of values into an Azquo database) and ties itself to the read counterpart by naming the shared AQL grammar and the query_aql sibling. An agent can immediately distinguish it from query_aql and from the other write-ish 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?

Explicitly enumerates two modes selected by options.createNames, gives a 'Use for:' line for each, adds a third structure-only mode, and states the mutual-exclusion constraint with ignoreHeadingErrors. Conditions are concrete enough that an agent can pick the right mode without 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?

With no annotations, the description carries the full behavioral burden. It implies a read-only audit and adds the useful prerequisite of re-supplying the originating query, but it discloses nothing about permissions, output format, cost, or limits for a tool that returns a provenance 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?

Three tight sentences, front-loaded with the purpose and followed by the use case and input note. No filler, though the parameter sentence introduces ambiguity rather than resolving it.

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 6-required-parameter tool with no annotations, no output schema, and 50% schema coverage, the description is too thin. It neither accounts for the three unexplained parameters nor describes the shape of the provenance result the agent will receive, and it references an 'AQL query' input that does not correspond to any schema field.

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 only 50%, and the description explains only row/col (already documented in the schema) while leaving context, rowHeadings, and columnHeadings completely undocumented in both places. Worse, it instructs the agent to 'provide the same AQL query,' but no query parameter exists in the schema, so the mapping between the described input and the actual required fields is unclear.

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 ('Get the provenance/audit trail for a specific cell in an AQL query result') and explains the value proposition (tracing which imports, calculations, or source data contributed). It is distinguishable from most siblings, though it never names the closely related query_aql or describe_query tools to sharpen the boundary.

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 a clear when-to-use condition ('useful for tracing where a value came from') and states the prerequisite that you supply the query that produced the result. There is no when-not guidance or explicit routing to an alternative, so it stops short of a 5.

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 no annotations supplied, the description carries the full burden and does so: it discloses destructive behavior (an existing database with the target name is REPLACED and local edits are lost), that no key is needed, and that the server uses a public read-only key. This is exactly the context an agent needs before a write operation.

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 the user-confirmation directive, then the destruction warning and key note. Every sentence earns its place, though the instruction set is dense and the parenthetical gloss on azquo_skills is slightly redundant.

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 1-parameter, no-output-schema tool with no annotations, the description covers purpose, trigger conditions, prerequisites, destructive consequences, and auth behavior. An agent has everything needed to call it 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 schema already documents the single 'target' parameter and its default. The description adds the consequence of the target name colliding with an existing database, which is useful but mostly behavioral rather than a parameter-syntax clarification. 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?

States a specific verb (copy), a specific resource (the azquo_skills usage-skills database), the source (data.azquo.ai), and the destination (current business). An agent can distinguish this from sibling copy_from_library 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?

Explicitly says when to use it (offline/local copy), that it can be re-run to refresh, that the user must be asked first with a specific confirmation string, and references the sibling tools list_databases and current_business for the prerequisites. 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?

With no annotations provided, the description carries the full burden and does so: it discloses non-destructive collision handling ('nothing is ever overwritten', suffixing to name_1/name_2), name sanitisation rules (spaces to underscores, punctuation dropped), and the requirement to surface the returned `target` name. These are exactly the behaviors an agent could not infer from the schema.

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 in the first sentence, then moves through guardrail, tool references, collision behavior and result reporting in a tight sequence. Every sentence carries distinct operational information; none 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?

No output schema exists, so the description compensates by explaining the `target` field in the result and warning that it may differ from the requested name. Prerequisites, collision semantics and the correct confirmation question are all covered, so an agent has everything needed to call 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% and the single parameter already documents that the name must match list_library output, so the description's restatement of that rule adds little. The sanitisation note is about the resulting target name rather than the input argument, leaving this at the baseline for a fully documented single-parameter tool.

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+scope: 'Copy one database from the shared Azquo library into the current business', and enumerates what travels with it (reports, import templates, uploaded file types). This distinguishes it cleanly from siblings such as copy_azquo_skills, try_on_copy and create_database.

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 precondition ('ASK THE USER FIRST ... wait for a yes'), an explicit prohibition ('never copy speculatively or as a side effect of a browse request'), and names the two sibling tools to consult instead — current_business for the target and list_library for valid names. 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the conditional server-ID requirement, but for a creation mutation it says nothing about permission needs, name-collision behavior, side effects, or error conditions, leaving the agent with an incomplete safety/behavior picture.

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 compact sentences with the primary action front-loaded and the one conditional detail following it. No filler or redundancy; every clause 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?

For a two-parameter creation tool this covers the essentials, and there is no output schema to explain. However, with no annotations describing a mutating operation, the description could do more to state whether it returns the new database identifier and what constraints apply to the name.

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 both parameters are self-documenting, so the baseline is 3. The description restates the databaseServerId conditionality that the schema already expresses, adding reinforcement but no new syntax, format, or constraint 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 and resource ("Create a new Azquo database"), which is unambiguous and distinguishable from delete_database, list_databases, and describe_database. It does not explicitly name or contrast with siblings, but the action is clear enough that an agent can route to it 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?

The description gives one concrete usage condition: databaseServerId is only needed when multiple servers exist. That is useful, but there is no guidance on prerequisites, permission requirements, or when to prefer another tool (e.g. persist_database, apply_structure) for related setup tasks.

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?

No annotations exist, so the description carries the full burden and does so: 30-minute link lifetime, unlimited file count, server retains the original and creates a Markdown copy, the link itself is the only credential (no API key), nameId side effects (DOCUMENT/IMAGE attributes added to the name, file never stored in the name), and the network-access failure mode with remediation.

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 progressively adds edge cases. Dense with no filler sentences, but the long paragraph on sandbox POSTs and the run-on line about link lifetime make it heavier than it needs to be for a 3-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?

With no annotations and no output schema, the description still covers lifetime, capacity, what is stored, credential model, side effects, and the post-call workflow. An agent has everything needed to invoke it correctly and handle failures.

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 goes beyond the schema for nameId by explaining the resulting side effect (a DOCUMENT <id> / IMAGE <id> attribute appended to a Meta info note) and the intent of the field. The 'note' parameter's semantics are left entirely 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: 'Get a link where the USER uploads documents ... to keep with a database.' It immediately frames the tool's role (hosted upload page) and distinguishes it from file-importing siblings like import_file/import_from_url and from read_document/list_documents which it references.

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 ('Use this whenever a file should be stored in Azquo - NEVER base64 a file into a tool call'), when-not (self-made sandbox files should be POSTed via curlCommand rather than re-uploaded by the user), and the follow-up action ('Afterwards call list_documents'). Routing between this tool and the alternative upload path is fully specified.

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 no annotations, the description carries the behavioral burden, and it delivers non-obvious context: the tool exposes whether an 'acting-as override is in effect', a session-state nuance not inferable from the name or empty schema. It does not explicitly declare read-only/no-side-effects, but 'Return' strongly implies a pure read for a zero-parameter tool.

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 tightly written sentences: the first defines the return content, the second front-loads the usage trigger. No redundant restatement of the name and nothing to trim.

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 zero-param, no-annotation, no-output-schema tool this is nearly sufficient: it enumerates what is returned (business, user, acting-as override), so the absent output schema is largely compensated. Only minor gaps remain, such as whether any side effects or permissions are involved.

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 schema is by definition complete and there are no parameter semantics to add. The baseline for a 0-parameter tool is 4.

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 ('Return') and a precise resource: the currently effective business, the user, and the acting-as override state for this MCP session. It is clearly distinguishable from siblings like list_businesses (enumerate all) and switch_business (mutate the session), none of which report the session's effective identity.

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 call condition ('Use before any destructive action'), which is actionable guidance tied to a safety workflow. It stops short of naming alternatives or stating when the tool is unnecessary, so it is strong context without full when/when-not coverage.

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 no annotations provided, the description carries full behavioral burden, and it does disclose the single most important trait: irreversibility ('Permanently', 'cannot be undone'). However, it omits other consequential behavior such as required permissions, whether deleting a persisted database fails or cascades, and what happens to dependent names/reports.

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 short, front-loaded sentences with zero filler. The destructive nature and the identifier requirement are both stated immediately.

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 one-parameter destructive tool with no annotations and no output schema, the description conveys the operation and its irreversibility, which may be sufficient for invocation. It nevertheless leaves gaps around authorization requirements, side effects on related objects, and failure modes that an agent weighing a permanent delete would benefit from.

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 single 'name' parameter is fully documented in the schema, so baseline is 3. The description's 'by name' phrasing only restates what the schema already says and adds no format, lookup, or validation detail.

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 ('permanently delete') and resource ('an Azquo database by name'), which clearly separates it from sibling deletions like delete_name, delete_report, and delete_import_template. An agent can identify the target object type and operation 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?

The description gives no when-to-use guidance, no prerequisites, and no alternatives or recovery paths (e.g., restore_name, persist_database). The only usage-relevant signal is the implicit caution from 'cannot be undone', which is inferred rather than 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?

No annotations are provided, so the description carries the full behavioral burden. It fails to say whether the deletion is permanent or reversible, whether it requires special permissions, whether it affects dependent schedules/uploads, or what happens on a non-existent ID. For a destructive mutation tool, that is a substantial gap.

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?

One short sentence with the verb and resource front-loaded and zero wasted words. It is appropriately sized for a one-parameter tool, though it is terse to the point of omitting useful caveats.

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 simple one-parameter tool with no output schema, the description covers the basic operation adequately. However, as an unannotated destructive operation it should disclose irreversibility or side effects, which it does not.

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% for a single 'id' parameter, so the schema already documents the input. The description adds only the mild clarification that the ID is numeric and identifies an import template, which is marginal value beyond the schema 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 (delete) and resource (import template) plus the identifier form ('by its numeric ID'), so the agent knows exactly what the tool operates on. It does not name or distinguish itself from any sibling such as list_import_templates, but the purpose is unambiguous on its own.

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?

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no warning about consequences of deletion. The agent must infer everything about appropriateness and timing from the name alone.

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 no annotations provided, the description carries the full behavioral burden and does so well: it discloses permanence, the cascade deletion of values plus uploaded documents/images, the response field (documentsDeleted), the 404 error path, and the mandatory audit-trail provenance fields. This is exactly the destructive-operation 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-loaded with the destructive action, then cascade scope, lookup source, and error behavior — a sensible priority order. The provenance block is justified because those parameters are required, though 'Lands in the audit trail' repeated on both lines is mildly redundant.

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 and no annotations, the description supplies the key return signal (documentsDeleted), the failure mode (404), and provenance requirements. It does not enumerate the full response shape, but it covers what an agent must know to call and interpret the result 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 already 100%, so the baseline is 3, but the description adds real meaning: it explains the id provenance for nameId and that source/agent land in the audit trail, framing them as required provenance rather than arbitrary strings. That exceeds what the schema fields convey.

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 (permanently delete) and resource (a name), and immediately distinguishes itself from siblings like delete_database, delete_report, and edit_name_attributes by scoping to names and warning of cascade effects. An agent can tell exactly what this does 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?

Gives clear operational context: how to source the nameId (apply_structure namesResolved, describe_set, describe_query) and what happens on a miss (404). It stops short of explicitly contrasting with the natural alternative, restore_name, or noting that list_deleted_names exists, so the when-not-to-use guidance is implied rather than 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?

With no annotations, the description carries the full behavioral burden. 'Delete' implies a destructive write, but the description never states whether the deletion is permanent or recoverable, what permissions are required, or what happens to a report referenced elsewhere. Siblings like restore_name and list_deleted_names suggest a restore/soft-delete concept exists in this API, yet the description is silent on which applies here.

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?

One short sentence with the action and identifier front-loaded and zero wasted words. Appropriately sized for a single-parameter destructive 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?

For a destructive operation with no annotations and no output schema, the description is too thin: it omits reversibility, required permissions, and error behavior for an invalid or already-deleted ID. An agent can invoke it, but cannot predict the consequences of doing so.

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 'id' parameter is already documented in the schema. The description's 'numeric ID' phrasing adds only a marginal hint beyond the schema's integer type. 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 and resource ('Delete an online report') plus the identifier type, so the action is unambiguous. It does not differentiate itself from the other delete_* siblings (delete_database, delete_name, delete_import_template), though the distinct resource noun makes misrouting unlikely.

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?

No when-to-use or when-not-to-use guidance is given; there is no mention of prerequisites, confirmation expectations, or an alternative such as list_reports for finding the ID. The agent must infer the usage context entirely from the tool name.

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?

No annotations exist, so the description carries the full burden. It discloses the read-only nature implicitly via 'overview' and explains the returned data shape (sets, child counts, attributes, meta-info subtree), which is valuable since no output schema exists. It omits cost/profile details, but for a read-only describe call this is largely sufficient.

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, front-loaded with the concrete return contents followed by the usage recommendation. Every clause earns its place with no 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 no annotations, the description does the necessary work by describing what the call returns. Combined with 100% schema coverage on the three inputs, an agent has enough to call it correctly; only deeper behavioral traits (cost, limits) are 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 coverage is 100%, so the schema already documents depth, database, and attributes. The description's mention of the 'meta information subtree' and 'available attributes' loosely maps to the depth and attributes parameters but adds no syntax or format detail beyond the schema. 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?

States a specific verb (get an overview) and resource (an Azquo database) and enumerates exactly what comes back: top-level sets with child counts, available attributes, and the meta-information subtree. It is clearly distinguishable from siblings like describe_set, describe_query, or query_aql.

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 to use it as the first step when exploring an unfamiliar database and contrasts it with 'multiple AQL probes', naming the alternative workflow it replaces. It stops short of stating when NOT to use it (e.g. when the schema is already known), but the positioning guidance is strong.

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 no annotations, the description carries the full burden, and it does well: it discloses that internal/user storage attributes are filtered out by the server, that AI Text bodies are included, that entries carry an integer id for chaining, and that limit defaults to 50. It stops short of stating read-only/safety semantics or permission requirements, which would complete the picture for a mutation-adjacent tool.

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 return shape before the syntax reference, so an agent gets the essential meaning immediately. The syntax examples are somewhat extensive, but they earn their place as non-obvious grammar that cannot be inferred elsewhere.

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 explain return values, and it does thoroughly: parents, attribute values including AI Text bodies, child counts, and ids. Combined with the server-side filtering note and chaining guidance, an agent has everything needed to call and use 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?

Schema coverage is 100%, so a baseline of 3 applies, but the description goes well beyond the schema by explaining the query grammar: postfix set verbs, the invalid prefix 'children of X' form, set-algebra operators (*, +, -), assignment forms, and mutation primitives. This materially clarifies how to construct the query parameter.

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 details exactly what is returned: matched names with parents, attributes, and child counts. It is clearly distinguishable from sibling discovery tools like list_names and describe_set by its focus on resolving queries and surfacing attribute values.

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 to use it 'after list_names / describe_set to read attribute values that the other discovery tools don't surface,' naming alternatives and the condition that selects this tool. It also notes the returned id chains directly into edit_name_attributes or delete_name, preventing a separate lookup.

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 no annotations, the description carries the full burden and does well: it discloses the return shape (child names, counts, parent path) and the round-trip cost model (1+N vs single call). It stops short of stating permission/auth requirements or pagination/size limits for large depth values.

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 and routing are front-loaded in the first two sentences, and the longer example paragraph justifies its length by encoding a non-obvious combined-call pattern. Slightly verbose, but every sentence contributes.

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 describe returns, and it does (child names, counts, parent path). Combined with the usage routing and the optimization guidance, 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 already 100%, so baseline would be 3. The description adds real meaning beyond the schema by explaining the depth+attributes interaction and giving a concrete worked example (depth=2, attributes=["AI TEXT"] on 'Start here'), which clarifies how depth and attributes compose.

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 ('Drill into a named set') and precisely enumerates what is returned: child names with counts plus the parent path. It distinguishes itself from siblings by positioning itself after describe_database and contrasting with describe_query.

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 states when to use it ('after describe_database to explore a specific set') and names the alternative path (one describe_query per child). It also gives a clear preference rule for topic reads, telling the agent exactly which call pattern to choose.

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 no annotations, the description carries the full burden and does so well: empty-string values delete attributes, unmentioned attributes are preserved (explicitly NOT wipe-and-replace), 404 on unknown id and 'silent no-op is never the result', plus why source/agent are mandatory (audit trail). These are exactly the destructive-semantics and error-behavior facts 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-loaded with the core behavior, then lookup, then a clearly delimited PROVENANCE block. Every sentence earns its place; nothing is redundant with the 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?

For a 5-required-param mutation with no annotations and no output schema, the description covers mutation semantics, id provenance, error behavior, and mandatory audit fields. The only gap is the shape of a successful response, which is not described.

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 value beyond the schema: it explains the deletion convention, the verbatim string storage implication, and the rationale for the provenance fields (they land in the audit trail so the user can trace the edit). Only nameId/database get no extra semantic depth.

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 opens with a precise verb+resource+scope: 'Surgical attribute edit on an existing name,' and immediately distinguishes the operation from wipe-and-replace semantics. It is clearly separable from siblings like delete_name, apply_structure, and aql_write.

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 tells the agent where the required nameId comes from (apply_structure's namesResolved, describe_set, describe_query) and reveals a non-obvious usage path: renaming is done by setting default_display_name through this same call. It stops short of stating when to prefer this over aql_write or apply_structure for attribute changes.

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?

No annotations are provided, so the description carries the full behavioral burden. 'Fetch' implies a read, and it explains the conceptual return shape (named regions, 2D value arrays, choice filtering), but it never states permissions, rate limits, error behavior, or whether choices must pre-exist. Useful domain context, incomplete behavioral profile.

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 core action is front-loaded in the first sentence, and the following paragraphs are logically ordered (what a report is, then how to call it). The domain primer is on the verbose side but each block is coherent and readable.

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 no annotations, the description does the heavy lifting by describing the return structure (regions, headings, 2D arrays, resolved choice values). The main gap is that it omits any safety/permission framing for what is effectively a data-retrieval call.

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 echoes schema facts (reportId as ID or name, required database) and adds a richer choices example ('Month'/'Department'), which is marginally helpful but does not go beyond what the schema already documents, including its own choice example and allowed value types.

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 ('Fetch the full data for a report') and immediately scopes what 'full data' means (all regions and current choice values). This clearly distinguishes it from siblings like list_reports or describe_database.

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 implies its use case (retrieving report contents) but never names alternatives such as list_reports or the query/describe siblings, nor states when not to use it. Domain context about what reports are helps understanding but is not routing guidance.

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 no annotations, the description carries the full burden and delivers: clear is NOT REVERSIBLE, requires confirm: 'CLEAR', requires an administrator or the owning developer, and requires provenance (source and agent). These are exactly the safety and auth traits an agent needs before invoking a destructive action.

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 purpose sentence followed by a tightly structured per-action list; every line (default get, dev-workflow rationale, irreversibility, confirm token, auth) earns its place. No 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?

For a destructive-config tool with no output schema and no annotations, the description supplies auth requirements, provenance fields, the irreversibility warning, the confirm token, and even the return shape of get. Nothing an agent needs 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, and the description adds real meaning on top: it explains what each action enum value does, why agent/source are required (provenance), and the exact confirm token. It even describes what get returns, which the schema cannot convey since there is no output 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: reading or changing whether a database records value/name/set history, plus clearing it. It explicitly names the related concepts (audit_cell, name_history) so an agent can distinguish it from those sibling tools. No ambiguity about what the tool governs.

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?

Enumerates each action with a when-to-use condition: off during development when every test import rewrites the DB, on to resume, clear typically at end of development, get as the default. It also gives an explicit exclusion, '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?

With no annotations, the description carries the full burden and does so well: it discloses the 256 KB hard cap and refusal behavior, that data crosses the agent's context, the latency contrast (minutes vs ~0.1s), and the auth/business-header detail on the alternative route.

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 uses a clean bulleted routing list. It is slightly long with heavy ALL-CAPS emphasis, but almost every sentence carries routing or constraint 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 covers everything an agent needs: purpose, size ceiling, transport cost, and explicit alternatives with their prerequisites. Nothing material is missing for correct invocation.

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 documents all three parameters; the description mostly restates them, though 'Filename selects the import template' and the restated size cap reinforce the schema's meaning. 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 precise verb, resource and scope: import small inline base64 data into an Azquo database via `fileContent`. It explicitly contrasts itself with `import_from_url` and the raw HTTP route, so an agent can distinguish it from siblings 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 (data exists solely in context and no shell available), when-not-to-use (anything fetchable by URL or when curl is available), and names both alternatives with the conditions that select them. Routing is unambiguous.

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 no annotations, the description carries the full burden and discloses key behaviors: the server connects and fetches, credentials are held server-side and never exposed, rows never pass through context, and only read-only queries are allowed. It also advises checking 'values adjusted' in the result. It omits error handling, rate limits, and sync/async details, so it is not a perfect 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 and safety, then structured with clear guidance. However, the multi-paragraph heading explanation duplicates the schema's parameter description, which reduces conciseness. The framing as 'two ways to say what the columns mean' does earn its place as a decision aid.

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 annotations and no output schema, the description is complete enough: it covers the safety profile, prerequisites, import path, and a result validation step. It fully equips an agent to select and invoke 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%, and the schema already documents all five parameters, including a detailed description of the headings semantics that covers one-off versus recurring use. The description's explanation of headings largely restates that schema text, so it adds no new parameter meaning beyond 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 (import) and resource (SQL result into an Azquo database) and distinguishes itself from other import routes by specifying a configured external database connection. An agent can immediately tell this is for querying external DBs, not for files or URLs.

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 states the right use case (a business's own internal database) and what to do if the connection is missing (ask an administrator rather than looking for another route). It also names prerequisite helpers like list_external_connections and list_import_templates, effectively routing the agent without ambiguity.

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 no annotations, the description carries the full burden and does substantial work: it discloses that the server fetches the URL (no context cost), that the target file needs a self-describing Azquo header, that the file name drives import instructions, and it warns that a completed import is not proof of a correct one. It omits auth/permission requirements and any rate or size limits, but the behavioral picture is otherwise strong.

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 server-side download advantage, then the requirements and fallbacks. It is longer than average but information-dense; minor redundancy between the header/name remarks and the schema text keeps it from a 5.

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 describe returns, and it does ('the same validation summary including lines imported and values adjusted'), plus a caution against reading a completed import as correct. Prerequisites (Azquo header row, file name), alternatives, and fallbacks are all covered, making it callable end-to-end.

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 five parameters are already documented, and the baseline is 3. The description reinforces the importance of filename and headings but introduces no syntax or format detail beyond what the schema already provides.

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+mechanism ('Bulk-load a delimited-text or spreadsheet file into a database by URL') and clarifies an execution property the name obscures ('THE SERVER DOWNLOADS IT'). It explicitly distinguishes itself from the sibling import_file, so an agent can route correctly 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 when-to-use ('anything large', 'anything beyond a few KB'), named alternatives (import_file, POST /api/importdata), and a when-not pathway for data that exists only in context. The selection logic is fully spelled out with no inference required.

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 no annotations, the description must carry the behavioral load, and it does disclose a non-obvious trait: the list is derived from the API key owner's email, one entry per business that email belongs to. That scoping rule is genuinely useful. It omits any statement about read-only safety, pagination, or ordering.

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 short sentences, front-loaded with what is returned, then the derivation rule, then the follow-on tool. Every sentence adds information an agent needs; none 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?

For a no-param read tool with no output schema and no annotations, the description covers scope, derivation, and the related tool. It does not hint at what each business entry contains (name, id), which is the only remaining gap an agent might want.

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, which is the baseline-4 case. The description correctly implies a no-argument call and adds that no filtering is needed or possible.

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 ('List the businesses') and immediately scopes it to 'this MCP session can switch between', which is not derivable from the name alone. It is clearly distinct from the many other list_* siblings (list_users, list_databases) because it names the session-scoped business set.

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?

Names the direct follow-on action and its trigger: 'Use switch_business to change the active one.' It does not say when to prefer this over current_business or establish any exclusions, so it stops short of a full when/when-not/alternatives treatment.

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?

No annotations are provided, so the description carries the full behavioral burden. It thoroughly explains result semantics: overlay entries carry overlay/readOnly/openWrite flags, library entries carry library: true, and local DBs never carry overlay flags. It does not explicitly state that the operation is side-effect free, nor mention ordering, pagination, or error behavior, so it stops short of a 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?

The purpose is front-loaded in the first sentence, and subsequent sentences earn their place by explaining the otherwise non-obvious overlay model. It is dense but not wasteful, though it could be tightened slightly without losing meaning.

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 explain what the tool returns and how to interpret it. It does so completely: it describes the two shared overlays, the meaning of overlay/readOnly/openWrite/library flags, and how library entries differ from writable copies. An agent has everything needed to call the tool and interpret its results.

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 is 4. The description adds no parameter information because none is needed; the schema covers everything.

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 ('List all Azquo databases') and immediately scopes it to the current user. It goes further by explaining the overlay model and naming the relevant siblings (describe_database, query_aql, copy_from_library), so an agent can distinguish this tool from adjacent listing and access 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?

Explicitly tells the agent when to read overlaid library entries in place with describe_database / query_aql and when to use copy_from_library instead ('only when the user actually wants their own writable copy'). This is direct when/when-not/alternative guidance.

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 no annotations, the description carries the full burden and does disclose return behavior: results are grouped into three named kinds, counts per group are included, and a group is simply empty when none exist. It doesn't cover auth/rate limits, but for a safe list operation the disclosed return shape and grouping semantics are the key traits.

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 the three groups before the sibling comparison. It is somewhat long, and the parenthetical glosses on each group are slightly expansive, but every clause carries usable routing or return-shape 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?

There is no output schema, so the description must explain return values, and it does: grouped into three kinds with per-group counts and empty groups when absent. Combined with the sibling differentiation, an agent has what it needs, though ordering and exact response format remain unspecified.

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 single parameter is fully documented as 'Database name'. The description reinforces the scope ('the one database named') but adds no format, casing, or ID-vs-name syntax 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+resource ('List every Excel workbook associated with one database') and immediately names the three groups returned. It also differentiates itself from siblings list_reports and list_import_templates by explaining those are business-wide while this is database-scoped.

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 framing ('Use this to answer what spreadsheets come with this database?') and names the alternatives (list_reports, list_import_templates) with the condition that selects this tool instead (scoped to the one database named). 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?

With no annotations to lean on, the description carries the full burden and does so well: it discloses result ordering (most recent first), the per-row metadata, that ids persist in history, and the history_settings caveat that scopes what can be returned. This is exactly the kind of non-obvious behavior an agent needs before trusting the output.

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 what is returned, then filtering, then follow-up tool routing, then the precondition. Every sentence earns its place, though the return-content enumeration is dense enough to slow the first read slightly.

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 and no annotations, so the description must cover the return shape and safety context itself, which it does by naming the fields returned and the history-recording constraint. Nothing an agent needs to call this list 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 all three parameters are already documented. The description restates parentId's narrowing behavior (matching the schema's 'only names deleted from it') but adds no format or edge-case detail, and says nothing about limit beyond the schema's default of 100. 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 ('names that have been deleted') and immediately enumerates the returned content: deletion order, actor, timestamp, child count, and set membership. An agent can distinguish this 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?

Explicitly routes the agent: pass a deleted name's id to name_history for its last attributes, or to restore_name to bring it back. It also states the precondition that only deletions made while history recording was enabled appear, which is a genuine when-not condition.

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 no annotations, the description carries the full burden. It usefully discloses ordering ('newest first') and null semantics for markdownChars (with markdownNote explaining why), which is real behavioral context. However it says nothing about pagination, result limits, permissions, or performance for large document sets.

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 trailing clauses on return fields and the nameId filter each add information. The markdownChars/markdownNote clause is long and nested, but it earns its space since no output schema exists.

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 two-parameter tool with no annotations and no output schema, the description compensates well by enumerating the returned fields and their semantics. Missing pagination and access expectations keep it short of complete.

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. The description's 'Pass nameId for one name's documents' essentially restates the schema's own note, adding no format, type, or edge-case detail beyond it. 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 ('List the documents stored with a database'), clarifies provenance (uploaded via create_upload_link), and names the exact fields returned. An agent can distinguish it from list_databases, list_names, and read_document 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 a concrete filter instruction ('Pass nameId for one name's documents') and situates the tool relative to siblings create_upload_link (how documents arrive) and read_document (the Markdown copy). It does not state explicit when-not-to-use conditions or an alternative listing tool.

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 no annotations, the description carries the full behavioral burden; it usefully discloses that credentials are never returned and that the server holds them, plus that setup is an administrator responsibility. It does not state that the operation is read-only, describe the return shape, or mention any rate/scope behavior, so it adds some but not rich 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-loaded with the core action, followed by downstream usage and then credential/setup caveats. Well organized, though the final sentence is slightly long and could be tightened.

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 zero-parameter, no-output-schema listing tool, the description covers purpose, downstream usage, and security behavior adequately. The main remaining gap is that it does not say what fields a listed connection exposes, which is minor 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?

The schema declares zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter meaning is missing.

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 ('List the external database connections configured for this business'), clearly distinguishing it from the many other list_* siblings (list_databases, list_names, etc.) and from import_from_query by noting it feeds the connection name into that tool.

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 how the output is consumed ('Use the connection NAME with import_from_query') and gives a fallback when the source is missing ('ask for it to be added rather than looking for another route to the data'). It lacks a direct when-not-to-use statement relative to sibling listing tools, so it stops short of a 5.

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?

No annotations are provided, so the description carries the full burden. It correctly signals a read operation and discloses that results are scoped to the current business/account, which is useful context, but it says nothing about ordering, pagination, or whether an empty list is possible for an account with no templates.

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?

A single front-loaded sentence with zero filler. The scope constraint is stated immediately and nothing redundant follows.

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 zero-parameter, read-only listing tool with no output schema, the description covers what is needed to invoke it correctly. It falls just short of complete because it never hints at what a template represents or how the result relates to import_file/import_from_query.

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 is 4 per the rubric. The description adds no parameter meaning, which is appropriate since there is nothing to document.

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 specific verb+resource ('List all import templates') and adds a scope qualifier ('available for the current business/account'). It is clear what the tool returns, but it does not explicitly distinguish itself from siblings such as delete_import_template or the import_* tools beyond the obvious verb difference.

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?

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives. The agent must infer that this is the discovery step before an import or template deletion, but nothing in the text states that.

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 no annotations, the description carries the full burden and does well: it discloses that all entries return in one call, enumerates the row fields including conditional nameCount/valueCount, and clarifies that copying is not automatic. It does not explicitly label the operation read-only or confirm no side effects, but the implication is strong.

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 return contents, then the usage/alternative. Every sentence adds information, though the field enumeration could be tightened. No filler or redundancy.

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 justifiably explains the return shape in detail (name, sector, complexity, features, status, description, nameCount, valueCount). Combined with the usage and sibling routing, 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?

The tool takes zero parameters, so the baseline of 4 applies. There is no parameter syntax to clarify and the description appropriately focuses on return contents instead.

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: browsing the shared Azquo library of example/demo databases. It distinguishes itself from sibling list_* tools by scoping to demo/example catalogues and names copy_from_library as the separate write 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?

Explicitly states when to use it ('answer questions like is there an example with setup sheets?'), tells the agent there is no separate search endpoint, and clearly delineates the copy step as a distinct, explicitly-requested action routed to copy_from_library.

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 no annotations, the description carries the full behavioral burden. It discloses the return content ("each name plus the sets it belongs to"), which is helpful since there is no output schema, but says nothing about permissions, case sensitivity, or how the two match filters interact beyond the schema's own note. Some disclosure, meaningful gaps remain.

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 tight sentences with the core behavior front-loaded and no wasted phrasing. It is efficient, though slightly sparse for a search tool with filter interactions.

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 4-parameter search tool with no annotations and no output schema, the description covers purpose and return shape but omits behavioral context that an agent would want, such as scope (active names only?), pagination/cap behavior, and filter precedence. Adequate but with clear gaps.

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 each of the four parameters (database, contains, startsWith, cardinalityCap) is already documented in the schema. The description only loosely restates "prefix or substring," adding no syntax or format detail beyond the schema. 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?

States a specific verb and resource (search names in a database) and the matching mode (prefix or substring). It is clear what the tool does, but it does not differentiate itself from closely related siblings such as list_deleted_names, name_history, or describe_set in the sibling list.

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?

"Useful for resolving an ambiguous label to the correct name" gives an implied use case, but there is no explicit when-to-use vs. when-not-to-use guidance and no named alternative (e.g., why not describe_set or list_deleted_names). Usage is inferable rather than 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?

No annotations exist, so the description carries the full burden, but for a zero-parameter read it has little to disclose. It does add genuine behavioral context by scoping results to the current user, yet says nothing about result ordering, pagination, or what a returned report entry looks like — and no output schema covers that gap.

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?

A single sentence with no filler, and the scoping constraint is front-loaded. Nothing could be trimmed 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?

For a simple zero-param list tool the description is nearly sufficient, but with no annotations and no output schema the agent still cannot know the shape or fields of the returned report entries (id, name, type), nor whether results are paginated. A short clause on return contents would close the gap.

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 no parameters (0 params, empty schema), so there is nothing for the description to clarify. Baseline 4 applies; no parameter meaning is missing or misstated.

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 ('List all online reports') with a scope qualifier ('available to the current user'), so the operation is unambiguous. However, it offers no differentiation from siblings that also enumerate resources (list_documents, list_names, list_library) or from the report-specific get_report_data/delete_report, so an agent must infer the boundary itself.

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?

No when-to-use guidance and no alternatives named. Nothing tells the agent whether this is a discovery step before get_report_data, how it relates to list_documents, or whether there are prerequisites. Usage is only weakly implied by the 'list' verb.

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?

No annotations are provided, so the description carries the full disclosure burden. It mentions no auth/permission requirements, no pagination or result-limit behavior, and no indication of whether 'current business/account' is resolved implicitly or must be set beforehand.

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?

A single front-loaded sentence with no filler or redundancy. Nothing is repeated from the name, and the scope qualifier is stated up front.

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 zero-parameter read tool with no output schema and no annotations, the description is minimally adequate but omits return shape (e.g., fields per user) and pagination behavior, which the missing output schema leaves unexplained.

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 there is nothing for the description to disambiguate. Baseline of 4 applies for a parameterless tool.

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 (List) plus resource (users) and a scope qualifier (current business/account). This clearly distinguishes it from sibling list tools such as list_businesses and list_names, though it does not explicitly name 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?

The description states what it returns but gives no when-to-use context, prerequisites, or reference to alternatives like current_business or list_businesses. An agent must infer the usage from the name alone.

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?

No annotations are provided, so the description carries the full disclosure burden. It states that history is written only on database persist (recent edits may not appear), history can be switched off or cleared (history_settings), empty results mean none recorded rather than no changes, only attribute and set membership changes are captured, and asAt date input means end of that day.

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 well-organized paragraphs: core behavior first, asAt semantics second, operational caveats third. The length is justified by the tool's complexity, and no sentences are throwaway, though a few parenthetical enumerations are slightly verbose.

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 no-annotation, no-output-schema history tool, the description covers what is returned (attribute and membership history, deleted-name last state), how asAt works, and critical limitations. The schema provides the remaining parameter details, so nothing essential 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 baseline is 3. The description adds meaningful end-of-day semantics for asAt and clarifies that it reconstructs attributes and set members as they were then. maxMembers and nameId details remain 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 the specific resource (history of one name) and enumerates exactly what it covers: earlier attribute versions with who/when, set membership changes, and last state for deleted names. Distinguishes from siblings by naming list_deleted_names for id lookup and audit_cell for value history.

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?

Explains deleted-name usage and explicitly points to list_deleted_names for ids, identifies audit_cell as the alternative for value history, and notes history_settings can disable history. Lacks explicit guidance on when to use this versus list_names/describe_database for current state, but alternatives are clearly indicated.

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 no annotations, the description carries the full burden, and it discloses the non-obvious behavioral trait: writes are queued in memory and only this call makes them durable. It does not cover idempotency, blocking behavior, failure modes, or permission requirements, but the durability semantics are the key missing piece and they are present.

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, zero waste, with the core action front-loaded before the explanatory context about queued writes. Every clause 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?

For a single-parameter tool with no output schema, the description covers the essential mental model of the write queue and durability. It omits error/return behavior and whether all write paths are covered by the queue, which keeps it from being fully complete.

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?

Only one parameter, and schema description coverage is 100% ('Database name'), so the schema already does the work. The description's phrase 'this database' adds no syntax, format, or scope detail beyond the schema, making the baseline 3 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?

States a specific verb+resource: 'Flush pending writes for this database to disk.' It also distinguishes itself from sibling write tools by explaining the in-memory queue model, so an agent can tell it apart from apply_structure or aql_write 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 the triggering siblings ('Edits via edit_name_attributes, apply_structure, AQL edit: primitives etc. are queued in-memory; call this to make them durable'), which is clear when-to-use guidance. It stops short of saying when persistence is unnecessary or whether it is mandatory after every write.

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 no annotations, the description must carry the behavioral load, and it does disclose real traits: the response shape, that values are raw types (string|number|boolean|null), and that results can be truncated with a maxRows default of 1000. It still omits error behavior on invalid AQL and any permission/authorization 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?

Purpose is front-loaded, followed by a compact conceptual model, a single worked example, and a response-shape block — each section earns its place and nothing is padding. The response block usefully substitutes for the absent 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?

For a nested, 5-parameter tool with no output schema and no annotations, the description covers request semantics, response fields, and pagination, which is a lot. The gaps are the unrelated-to-calling omissions: no guidance on sibling selection and no mention of error or permission 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 coverage is 100%, so the baseline is 3, but the description goes beyond it by explaining that each inner array is a heading expression equivalent to a cell formula, and by mapping rowHeadings/columnHeadings/context to a worked example. That conceptual framing is not recoverable from the schema 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?

The description states a specific verb and resource ('Query an Azquo database using AQL') and defines what AQL actually is, which is far more than a restated name. It implicitly distinguishes itself from the write-side sibling aql_write by framing the operation as a query, but it never names that sibling or any alternative explicitly.

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?

There is no statement of when to choose query_aql over neighbors like aql_write, get_report_data, describe_query, or import_from_query. The example illustrates how to shape a call, not when a call is warranted, so an agent gets invocation mechanics but no routing guidance.

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 no annotations, the description carries the full behavioral burden and does so well: it discloses pagination semantics (40000 default chars, truncated flag, nextOffset loop), the 60-minute downloadUrl expiry, the edge case where no Markdown exists (markdownNote + download link only), and an explicit behavioral instruction not to fetch the URLs itself.

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 pagination, then URL handling, then the no-Markdown fallback. Despite being dense, every sentence adds operational information an agent needs, with no 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 no annotations, the description compensates by describing the key return fields (truncated, nextOffset, downloadUrl, markdownUrl, markdownNote) and the fallback behavior. Nothing essential for correctly invoking or interpreting a call 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 genuine meaning beyond the schema: it ties offset to the nextOffset continuation value and confirms maxChars defaults, turning independently documented parameters into a coherent pagination protocol.

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') and names the fields preserved (headings, lists, tables). It also names list_documents as the discovery sibling, so an agent can distinguish it from read_workbook and other siblings 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?

It tells the agent when to reach for this tool and how to obtain the id (via list_documents or a DOCUMENT/IMAGE attribute), and explains the pagination follow-up ('when truncated is true, call again with offset = nextOffset'). It gives clear usage context but no explicit exclusions or named alternatives to avoid.

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 no annotations, the description carries the full burden and does so: it discloses formula-vs-computed-value preference, that it returns structure/text rather than the file (with the size reason), and the permission model (setup sheets and import templates are admin/developer only; reports follow the caller's report permissions).

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 sheet/no-sheet branching, and each sentence contributes distinct information (kinds, structure output, formula preference, non-file caveat, permissions). It runs a bit long but 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?

With no output schema and no annotations, the description compensates fully: it describes what each mode returns (sheet extents, defined names with scope/target, cell contents with formulas), the paging model via schema, and the access constraints.

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 documents all seven parameters including the sheet dual-mode, paging (fromRow/maxRows/maxCols), and defaults. The description restates the sheet behavior rather than adding new semantics, so 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 ('Read inside one workbook') and enumerates the three workbook kinds it covers. It distinguishes itself from siblings by naming list_database_sheets for discovery and contrasting its structural vs. cell-level modes.

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 clearly explains the two invocation modes ('Called without sheet... Called WITH sheet') and routes discovery to list_database_sheets. It also states an exclusion — use the admin's Download button if you want the actual file — though it doesn't contrast against report-data siblings like get_report_data.

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 no annotations, the description carries the full burden and does so well: it discloses the non-obvious semantics of the write (the name returns with a NEW id, attributes preserved, sets and children relinked 'where those still exist'), the critical destructive caveat that VALUES ARE NOT RESTORED, the return behavior (counts of relinked vs. failed), and the provenance linkage to the old id. This is exactly the behavioral context an agent cannot get from the schema.

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 behavior in the first sentence and uses a clearly delimited provenance block. The long em-dash sentence is dense but each clause (new id, attributes, sets, children, values not restored, response counts, provenance) earns its place. Minor redundancy in restating the REQUIRED provenance fields already in the 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?

For a 4-param mutation tool with no annotations and no output schema, the description covers side effects, the destructive caveat, and the response shape (relinked/failed counts). It omits permissions/auth requirements and whether a restore is itself reversible or repeatable, which are the only meaningful remaining gaps.

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 the schema: it tells the agent where nameId originates (list_deleted_names/name_history), what 'source' represents (why it is being restored), and why the provenance fields are required on every write. That is more than a restatement of the field 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 and resource ('Bring back a deleted name') and distinguishes itself from siblings by naming where the id comes from (list_deleted_names, name_history) and contrasting with delete_name. An agent can tell exactly what this does versus delete_name or name_history 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?

Explicitly routes the agent to the sources of the required nameId ('ids from list_deleted_names or name_history'), which is the key prerequisite for invoking it. It does not state when-not to use it or any conditions under which a restore should be avoided, so it stops short of full when/when-not guidance.

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 no annotations, the description carries the full behavioral burden and does so well: it discloses session-scoped side effects ('this MCP session's alone: other agents or chats on the same key stay where they are, and a new session starts in the key owner's own business'), the authorization constraint ('Target must be one the current bearer can reach'), and a data-integrity caution about pending writes. This is exactly the context an agent needs before a state-changing call.

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 sentences, all front-loaded with the core purpose first, then scope, then prerequisites, then params. Each sentence earns its place, though the Azquo_Skills cross-reference and the session-scope sentence make it slightly dense for a small switch 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?

For a tool with no annotations, no output schema, and only three well-documented params, the description covers purpose, scope, authorization, mutual-exclusivity, and a write-persistence pre-condition. Nothing an agent needs 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, but the description adds a mutual-exclusivity constraint ('exactly one of businessName, businessId, or userId') that the empty required list does not express. That constraint is genuinely useful and above what the schema conveys.

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 ('Switch the active business') and scopes it precisely to 'subsequent MCP tool calls in this session', which cleanly separates it from the read-only current_business sibling. An agent can tell exactly what this does and what it affects 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?

Gives concrete guidance: 'call list_businesses first if unsure', 'Provide exactly one of businessName, businessId, or userId', and a pre-condition to persist pending writes. It lacks an explicit contrast with current_business (its natural read counterpart), so it stops short of a 5.

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 no annotations, the description carries the full burden and does so richly: it discloses that every read and write in the session is redirected to the in-memory copy, that results are prefixed 'TRIAL COPY of ...', that nothing is ever saved and there is no commit, that a large copy lives in server memory, that an idle copy is purged after 2 hours with loud failures, and that the trial is scoped to this MCP session only. It even lists the tools refused while a trial is active.

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 it is front-loaded with purpose and every sentence conveys information an agent needs to operate a stateful session tool correctly. Density is high with little redundancy, though it is on the verbose side; the key constraint and workflow could be slightly tightened.

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 no annotations, the description fully compensates: it explains result format ('TRIAL COPY of ...' prefix), the outcomes of each action, the no-commit semantics, the memory/timeout failure modes, session scoping, and refused operations. Nothing needed to invoke and interpret 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 what each of the three action values does (start creates the copy, discard throws it away, status lists trials) and clarifies that the database parameter is needed for start and discard. This goes beyond the schema's terse enum labels.

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 before making them for real.' This is unambiguous and clearly distinguished from every sibling (which act on the real database). An agent can immediately tell what this tool is for.

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 is given ('a risky restructure, a bulk edit, or a first attempt at an unfamiliar write'), along with the full workflow route (start -> inspect with query_aql/describe_set/get_report_data -> discard or re-apply) and the crucial guidance that there is no commit. It also names the condition under which it should be avoided (large databases consume memory).

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