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

No annotations provided; description does not disclose whether the operation is read-only or any other behavioral traits beyond the return type. More detail needed.

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 with core purpose upfront, no wasted words. Efficient and clear.

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

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

Covers main purpose, return value, and alternative tool, but could mention relationship to akb_history and clarify optional parameter usage.

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 has descriptions for all parameters (80% coverage, actually all 5 are described). The description does not add new meaning beyond the schema, 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?

Clearly states it gets activity history for a vault, specifies what it returns (Git commit history with changed file list), and distinguishes from sibling akb_diff.

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 suggests using akb_diff for content changes, providing alternative guidance. However, lacks explicit when-not-to-use context for other siblings.

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 that admin role is required and that it executes ALTER TABLE DDL, but it does not mention side effects, transactional behavior, reversibility, locking, or what happens if part of a multi-operation call fails. For a mutating DDL tool this is a significant transparency 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?

The description is brief and front-loaded: it states the action, the target, and the key operations in a single sentence, then adds the access requirement. There is no filler or repetition of schema details.

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?

This is a complex tool with 10 parameters, nested objects, no output schema, and no annotations. The minimal description does not explain the variety of schema modifications available (indexes, unique keys, column alterations), when to use them, or what the operation returns. The schema covers parameter details, but the overall tool context is incomplete for an agent to invoke it confidently.

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

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

Schema description coverage is 100%, so the schema already documents all parameters, including add_columns, drop_columns, alter_columns, indexes, and unique keys. The description itself adds little beyond the general ALTER TABLE framing, but because the schema fully covers parameter semantics, the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Modify') and resource ('a table's schema'), and names the core operations: add, remove, or rename columns. It clearly conveys that this is an ALTER TABLE operation, distinguishing it from table creation/drop tools like akb_create_table and akb_drop_table, though it does not explicitly name those 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?

The description gives no guidance on when to use this tool versus alternatives. It states that admin role is required, but there is no mention of when to prefer this over akb_sql or create/drop table, nor any exclusions or fallback conditions.

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

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

With no annotations provided, the description carries the behavioral disclosure burden and it does so well by stating both the postcondition (vault becomes read-only) and the authorization requirement (owner-only). It does not mention whether archiving is reversible or what the return value looks like, but the core behavioral traits are clearly disclosed.

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

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

The description is two short, focused sentences with no filler or repetition of schema content. The action and effect are front-loaded, and the owner restriction is the only additional fact included, which makes it highly efficient.

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 one meaningful required parameter and no output schema, the description provides the essential selection and invocation details: what the tool does, what state change it causes, and who may call it. The main omissions are reversibility and explicit relationships to sibling tools, but those are not critical for a straightforward mutation call with a single required parameter.

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 baseline is 3 even though the description adds no parameter-level detail. The vault parameter's meaning is adequately covered by the schema, and while the _vault_skill_ack parameter is documented there too, the tool description does not clarify the 'vault_skill' workflow any further.

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 action ('Archive'), a clear target ('a vault'), and the key consequence ('makes it read-only'), which distinguishes it from destructive siblings like akb_delete_vault even without naming them. The owner-only restriction adds a precise scope to the operation.

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 effect 'makes it read-only' implies when this tool should be used, and 'Only the owner can do this' establishes a clear precondition. However, it does not explicitly name alternatives or state when not to use it versus related tools such as transfer_ownership or delete_vault, so the guidance remains somewhat implicit.

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 behavioral burden and does so well: it discloses depth semantics, that collection rows are always emitted, default summary behavior, and the exact response shape including `truncated?` and `hint?`. It does not explicitly confirm that browsing is read-only or discuss permission requirements, but for a browse operation the disclosed behavior is substantial.

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 longer than a minimal definition but every sentence earns its place: purpose, addressing modes, depth semantics, summary behavior, and response shape. It is front-loaded with the primary purpose and then structured logically, though it could be tightened slightly by naming sibling exclusions.

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 11-parameter tool with no output schema, the description is remarkably complete: it covers both addressing modes, depth behavior, summary defaults, and the return object. The remaining omissions, such as explicit pagination semantics or permissions, are minor because the schema already documents offset, limit, filter, and content_type.

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 input schema already covers 100% of parameters, so the baseline is 3; the description adds value beyond the schema with the `tree -L N` analogy for depth, the URI-precedence rationale for drilling down, and the context-window rationale for `include_summary`. Not every parameter is enriched, but the key ones gain meaningful context.

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 specific verb-resource pair: 'Browse ALL vault content — documents, tables, and files — under a browse root.' It clearly indicates the broad traversal scope, which differentiates it from item-level operations like akb_get. However, it never explicitly names or contrasts sibling tools such as akb_drill_down or akb_search, so it falls just short of full sibling differentiation.

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 concrete in-tool guidance: use the URI form when drilling down from a previous response, and use depth semantics to control how far to descend. It also explains why summaries are opt-in for large vaults, helping the agent decide parameters. It does not explicitly tell the agent when to choose akb_browse over alternatives like akb_drill_down or akb_search, so no exclusions or alternatives are stated.

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

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

With no annotations provided, the description carries the behavioral disclosure burden and covers idempotency, the duplicate-collection outcome ({created: false}), the fact that the collection is empty, and the required role. It does not detail error cases or the success response explicitly, but the core behavior is transparent enough for safe invocation.

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

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

Every sentence earns its place: the first defines purpose, the second states behavioral guarantees, and the third gives the authorization requirement. The phrasing is direct, front-loaded, and free of filler.

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

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

Given the simple operation, complete parameter schema, and absence of an output schema, the description covers purpose, idempotency, duplicate behavior, and permissions. The only minor gap is that the successful-creation return value is implied rather than explicitly stated, but it is easily inferred from the idempotency sentence.

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 parameters. The description adds no new parameter-level meaning beyond what is in the schema; it neither clarifies summary usage nor the _vault_skill_ack contract beyond the schema text. Baseline 3 is appropriate.

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

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

The opening sentence states the action (Create), the object (empty collection/folder), and the location (inside a vault), which clearly differentiates it from sibling tools like akb_create_vault and akb_create_table. The word 'empty' also sets precise expectations about what this operation does not do.

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 the usage context—creating a folder in a vault—and adds a clear prerequisite ('Writer or higher role'), but it never names alternatives or says when not to use this tool. An agent must infer the boundary against akb_create_vault and akb_put.

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 the response URI shape, permission inheritance from collections, and browse visibility. But it does not mention duplicate-name conflict behavior, write permissions required, or other side effects beyond creation, leaving notable gaps.

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?

Every sentence earns its place: purpose, URI shape, placement semantics, column shape, and collection guidance. It is dense but not bloated, and the most essential information is front-loaded.

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 10-parameter creation tool with no annotations and no output schema, the description covers the core action, return URI, permissions, and placement. The detailed schema fills most remaining gaps, but the description could have explicitly guided vault/parent selection and noted conflict behavior to be fully self-sufficient.

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 90%, so the baseline is 3. The description adds meaning for `collection` by tying it to the URI path and browse visibility, and it reinforces column structure. It does not substantially clarify `parent`, `indexes`, or `unique_keys` beyond what the schema already says.

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

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

The description opens with a specific verb and resource: 'Create a structured data table in a vault.' It clearly differentiates this from sibling tools like akb_create_vault, akb_create_collection, and akb_put by naming the artifact type and giving the canonical URI structure.

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

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

It gives clear placement guidance: use `collection` to group the table under a collection, omit it for vault root, and expects tables to live alongside documents. It does not explicitly contrast with akb_alter_table or akb_drop_table, nor state prerequisites like vault existence, 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 provided, the description carries the behavioral disclosure burden. It is transparent about the access-controlled nature of vaults, and clearly states that external_git mode tracks the remote on a polling schedule and rejects user writes. It could also note permission requirements or default visibility, but the most important behavioral traits are disclosed.

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

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

Two concise sentences, front-loaded with the main purpose and followed by the key mode distinction. There is no redundant wording or repetition of schema details.

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

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

The description covers the core purpose and the externally significant mode. The schema already documents all parameters, including the nested external_git object and the unusual _vault_skill_ack field. A small gap is that it does not mention what the tool returns or any permission prerequisites, but for a creation tool with a rich schema this is adequate.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real semantic value by explaining that external_git changes the entire creation mode to a read-only mirror, with polling and write-rejection behavior, which is not fully obvious 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 opens with a specific verb and resource: 'Create a new knowledge base vault,' and clarifies what a vault is. It also distinguishes the external_git mode from a normal vault, making it easy to separate this from sibling tools like akb_create_collection or akb_delete_vault.

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 concrete guidance on when to use the external_git variant: pass it to create a read-only mirror, otherwise create a standard vault. It does not explicitly name alternatives or state when not to use this tool, but the primary use case is clear from the first sentence.

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 for behavioral disclosure. It does reveal the destructive side effects (removing from Git, search index, knowledge graph), which is useful. However, it omits any mention of permissions, reversibility, confirmation requirements, or what happens to dependent data, which are important for a mutation 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 concise sentences with no filler. The primary action is front-loaded, followed by the key side-effect information. Every word adds value, making it an exemplary model of brevity without under-specification.

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 delete tool with one required parameter and no output schema, the description covers the essential behavior and cascading effects. It might benefit from mentioning whether the delete is reversible or if there are any prerequisites (e.g., ownership), but overall it is sufficiently complete for an agent to make the 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 description coverage is 100%, so the schema already documents both parameters (uri and _vault_skill_ack). The description adds no extra meaning about the parameters, such as URI format or how the ack token is used. A baseline 3 is appropriate since 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?

The description clearly states the verb 'Delete' and the resource 'document', and adds the scope of removal (Git, search index, knowledge graph) which differentiates from similar tools like akb_delete_vault or akb_delete_collection. However, it does not explicitly name sibling tools or edge cases, so it stops short of a 5.

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 guidance is given on when to use this tool versus alternatives. It does not mention that akb_delete_file handles files, akb_delete_vault handles vaults, or when a document delete is appropriate. The agent is left to infer that any 'document' deletion goes here, without reasoning about alternatives.

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

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

With no annotations, the description carries full burden and does an excellent job. It discloses destructive behavior (cascade delete), a side effect (one git commit), and role requirements (writer/admin depending on table inclusion). This is more than most tool descriptions provide.

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

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

Three sentences, no filler. The core action is front-loaded, followed by conditional behavior and role requirements. Every sentence earns its place.

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

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

Given no annotations and no output schema, the description covers the critical behavioral aspects: empty vs non-empty handling, recursive requirement, cascade scope, git commit side effect, and role prerequisites. It does not explicitly state what happens if recursive=false on a non-empty collection (error vs no-op), but this is strongly implied. Overall quite 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 coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: it explains how 'recursive' behaves in practice (cascade deletion) and connects the table condition to elevated role requirements. This elevates it above 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?

The description states a specific verb and resource ('Delete a collection') and differentiates it from sibling tools like akb_delete_vault and akb_delete_file by focusing on collection semantics. It also clarifies the two distinct cases (empty vs non-empty) that define the tool's scope.

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

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

The description provides clear conditions for usage: empty collections delete the metadata row, non-empty require recursive=true. It also gives role-based prerequisites. However, it does not explicitly name alternatives or state when not to use this tool, though the resource-specific naming makes that mostly implicit.

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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It states the destructive action but does not mention irreversibility, permission requirements, impact on linked data, or the retry/ack flow referenced by the _vault_skill_ack parameter.

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 a single front-loaded sentence with no filler. It is concise and direct, though the brevity contributes to the lack of behavioral context.

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 alone should provide enough context for safe invocation, but it does not. An agent cannot tell whether deletion is permanent, whether special permissions are needed, or how this tool differs from similar sibling tools.

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 baseline is 3. The description adds little beyond the schema, only reinforcing that the uri parameter identifies the file. It contributes no additional meaning about the _vault_skill_ack parameter, which is already documented in the schema.

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

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

The description clearly states the action ('Delete') and the resource ('a file from vault storage'), with the identifying mechanism ('by its URI'). It is unambiguous in isolation, though it does not explicitly differentiate itself from sibling deletion tools such as akb_delete or akb_delete_vault.

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 guidance is given about when to use this tool versus the many sibling removal operations like akb_delete, akb_delete_vault, akb_delete_collection, or akb_unlink. The description does not mention prerequisites, conditions, or exclusions.

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 of behavioral disclosure. It is explicit about what is deleted (documents, chunks, tables, files, edges, Git repo), that deletion is permanent, and that permission is restricted to owner/admin.

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 one tightly worded sentence that leads with the action and consequence, then lists the data scope and permission constraint. Every clause adds necessary information without 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 an irreversible destructive operation with no output schema and no annotations, this description gives all critical details: what is deleted, that it cannot be undone, and who is allowed to invoke it. An agent can safely decide whether to call it.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description does not add meaning beyond the schema, which is acceptable but not enriching, so the baseline of 3 applies.

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

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

The description opens with a strong verb and resource: "Permanently delete a vault." It then enumerates exactly what gets destroyed and emphasizes irreversibility, which clearly distinguishes it from the sibling akb_archive_vault.

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

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

The description provides clear usage context: use this only when you intend permanent destruction, and only as an owner or admin. It does not explicitly name a non-destructive alternative like akb_archive_vault, so it falls 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 must fully disclose behavior. It mentions the output shows 'what was added/removed/modified,' which conveys the type of information returned. However, it lacks details on output format, pagination, or potential side effects, leaving some ambiguity.

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 two sentences, each serving a distinct purpose: defining the tool and providing usage guidance. It is front-loaded with the core purpose and contains no redundant 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?

Given the tool's simplicity (2 required parameters, no output schema), the description covers the essential aspects: purpose, parameters, and prerequisite tools. It could optionally describe the return format but is adequate for the complexity level.

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 description adds little beyond the schema. It does reinforce that the commit hash comes from akb_history or akb_activity, providing slight additional context but no new parameter semantics.

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

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

The description clearly states the tool obtains a content diff for a document at a specific commit, using a specific verb ('Get') and resource. It also distinguishes from siblings by referencing akb_history and akb_activity as prerequisite tools to find commit hashes.

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 explicitly instructs users to first use akb_history or akb_activity to find commit hashes, providing clear guidance. However, it does not explicitly state when not to use this tool or mention alternatives for other use cases.

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

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

No annotations are present, so the description carries the burden; it discloses the key operational boundary (uncommitted vs. claimed/retained images) and states that already-claimed images cannot be discarded. It doesn't explicitly say the action is permanent or irreversible, but 'Discard' and 'never committed' strongly imply destructive cleanup.

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 sentences with no redundant information; the action and primary constraint are front-loaded, the usage condition follows, and the limitation closes. Every sentence earns its place.

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

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

For a destructive cleanup tool with no annotations or output schema, the description supplies essential operational context: when to use it, what cannot be discarded, and how to identify the source URL. It could additionally state that the action is irreversible or describe the success/error response, but the core call-correctness information is present.

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 description does not add parameter-level detail beyond the schema itself. The references to the URL returned by akb_put_image and to akb_put/akb_update provide useful context but don't elaborate on individual parameters.

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 ('Discard') and resource ('document image upload that was never committed'), and distinguishes the tool's scope from the related put/update flows. Among siblings, it is the only cleanup/discard operation for unpublished image uploads.

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 'Use this only to clean up after a failed or abandoned akb_put/akb_update,' giving a precise trigger condition. It also provides an exclusion rule: images already claimed by a document or retained by a Git revision cannot be discarded, so an agent knows when not to call 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?

Discloses that empty match returns outline, and response includes truncated/hint fields. No annotations exist, so description carries full burden; it adequately describes read-only behavior and response 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?

Compact, well-structured, front-loaded with purpose. Every sentence serves a clear function with no 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?

Covers both modes, parameter usage, and response shape despite no output schema. Addresses edge case (empty match) and provides complete guidance for a 4-parameter tool.

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

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

Schema has 100% coverage, but description adds value by explaining mode interaction and filtering behavior (e.g., section substring match, pattern grep) beyond 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?

Clearly states it reads section-level (L3) content or lists headings, distinguishing it from siblings like akb_get (full document) and akb_grep (whole-document search).

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 describes two modes with use cases: outline for cheap structure discovery, sections for content retrieval. Could mention alternatives but provides strong 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 it clearly discloses irreversibility, scope ('all rows'), and the admin requirement. It stops short of describing cascade effects or what happens to related objects, but the core destructive behavior is explicit.

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 clauses deliver action, consequence, and prerequisite with no filler. The warning is front-loaded right after the verb, and the admin requirement closes it efficiently.

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

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

The description covers what gets deleted, that it is permanent, and who may perform it, which is sufficient for a two-parameter tool. It doesn't mention effects on related objects, but the schema already documents the URI format and auth token, so the remaining gap is small.

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 baseline applies; both uri and _vault_skill_ack are already fully documented in the schema. The description adds no parameter-specific meaning beyond that.

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 action (permanently delete) and resource (a table with all rows), which clearly distinguishes it from siblings like akb_delete_vault and akb_delete_collection. It doesn't explicitly contrast with the generic akb_delete, but the table-specific scope is unambiguous.

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?

Implies use when a table must be removed permanently and states the admin-role prerequisite, but it does not spell out when to prefer this over akb_delete or akb_alter_table. There is no explicit when-not-to-use guidance or named alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently describes failure behavior ('If old_string is not found or appears multiple times, the call fails with a clear error'), scope limitation, and the effect of replace_all. This is strong behavioral detail for a mutation 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?

The description is compact and front-loaded with the core purpose, then constraints, then usage guidance and the alternative. Every sentence contributes value without 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?

Given the 7-parameter schema with full coverage, the description is largely complete for selecting and invoking the tool. It could have explicitly named the full-document update alternative (e.g., akb_update or akb_put) and noted result/commit behavior, but what is present covers the main decision points.

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 baseline is 3. The description reinforces old_string uniqueness and replace_all behavior, but adds minimal parameter-level meaning beyond the schema, which already documents each parameter thoroughly.

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: 'Edit a single document by replacing exact text,' making the tool's core function immediately clear. It also distinguishes it from siblings by explicitly contrasting with akb_grep for multi-document find-and-replace and implying a difference from full-body update tools.

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

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

The description gives explicit guidance: use this tool for targeted single-document edits, including inline image insert/replace/remove, and use akb_grep with replace for find-and-replace across many documents. It also clarifies that old_string must be unique unless replace_all is used, which is a concrete usage 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 provided, the description carries the transparency burden. It discloses the conceptual output (independent bases and derived effective role) and implies a read-only analysis behavior. It does not explicitly state that no changes are made, nor does it discuss permissions or edge cases, so it adds moderate but not complete behavioral 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?

Two sentences deliver the core purpose, output contents, and a key differentiator with no wasted words. The main action is front-loaded, and the contrast with member lists 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 read/explain tool, the description covers what the tool does and what it returns (basis and effective role). It lacks explicit notes on errors, permissions, or output formatting, but these are not critical given the simple schema and clear purpose.

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

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

Schema description coverage is 100%, so the schema already documents both required parameters adequately. The description adds contextual meaning around 'vault' and 'user' (role relationship) but does not supply additional format or semantics beyond the schema.

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

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

The description names a specific action ('Explain why'), a specific resource (a user's role on a vault), and a concrete deliverable ('every independent basis, and the effective role derived from them'). It also differentiates itself from member-list tools by stating that a member list shows results, not reasons.

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

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

The description provides clear context for when this tool is the right choice: whenever the reasoning behind a role, rather than the resulting membership, is needed. It contrasts with member lists but does not explicitly name the sibling alternative or state when not to use this 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 full responsibility for behavior disclosure. It specifies that documents export 1:1, tables/files become OKF concept documents with resource pointers, reader role is required, and the return format is a {path: content} map. This is detailed and goes well beyond a simple 'export' statement.

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 concise yet information-dense, covering purpose, return format, parameter semantics, conversion behavior, role requirements, and an alternative in four sentences. Every sentence contributes meaningful detail without 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?

Given no output schema and moderate complexity, the description thoroughly covers the return value structure, transformation logic, format options, permission requirements, and a fallback path. It is complete enough for an agent to know what to expect and when to reject use.

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

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

Schema coverage is 100% so both parameters already have descriptions. The description adds extra meaning by explaining the 'format' parameter's current value ('okf') and its implications (markdown + YAML frontmatter, only required field 'type'). This adds value beyond the schema's brief notes.

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 clearly states the tool exports an entire vault as a portable knowledge bundle, using a specific verb (Export) and resource (vault). It distinguishes itself from sibling tools by describing the inline return format and mentioning an alternative REST endpoint for zip downloads.

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

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

The description provides clear context on when to use this tool (for inline bundle export) and explicitly points to the REST endpoint for a downloadable zip alternative. However, it doesn't enumerate comparisons with all sibling tools, though the alternative is sufficient for key use cases.

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

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

Discloses that the tool returns full content with metadata and supports version retrieval. No annotations provided, so description carries full burden; it accurately describes the tool's behavior without contradiction.

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

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

Two sentences that are direct and front-loaded with the primary purpose. No unnecessary words, efficient communication.

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 the tool's simplicity (2 parameters, no output schema), the description fully covers usage preconditions (obtain URI via browsing/searching), optional versioning, and return value. Complete for its complexity.

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 covers both parameters with 100% coverage. Description adds meaning by explaining the version parameter's purpose (reading a previous version from akb_history), going beyond schema 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?

Clearly states 'Retrieve a document by its URI' and specifies it returns full content with metadata. Differentiates from browsing and searching by indicating that akb_browse or akb_search should be used first to obtain the URI.

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 when to use this tool (after akb_browse or akb_search) and how to retrieve previous versions using a commit hash from akb_history. Provides clear guidance with alternatives.

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

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

No annotations are provided, so the description carries the full burden. It describes a download (read) operation without mentioning side effects. It does not elaborate on behavior beyond the basic action, but it is not misleading.

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 action, no unnecessary words. Every sentence earns its place.

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

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

For a simple download tool with clear parameters and no output schema, the description is complete. It covers purpose, source of URI, and destination.

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% with descriptions for both parameters. The description adds value by specifying the URI format and source, which goes beyond the schema.

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

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

The description clearly states the verb 'Download', the resource 'file from vault storage', and the destination 'to a local path'. It distinguishes from sibling tools like akb_browse and akb_put_file by referencing them as sources for the URI.

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 tells the agent to pass the URI from akb_browse or akb_put_file, providing clear context for when to use this tool. It does not explicitly state when not to use it, but the guidance is sufficient.

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 burden and does disclose a key behavioral trait: only owner/admin can grant, and rule-driven grants should carry a source_key to allow future self-withdrawal without affecting others. It does not describe overwrite semantics, but the schema's revision field covers retry behavior.

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

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

Two sentences are used efficiently: the action, the permission gate, and the one nuanced parameter guidance are all front-loaded. No filler or repetition of schema content.

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 the six-parameter schema with full descriptions, the tool is adequately specified for selection and invocation: purpose, permission requirement, and source_key rationale are present. No annotations or output schema exist, but the description plus rich schema covers the essential operation-level context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics for source_key beyond the schema: "so it can later withdraw its own reason without deleting anybody else's." It does not describe revision/_vault_skill_ack behavior, but those are already documented in the schema.

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

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

The description opens with a specific verb and resource: "Grant vault access to a user," which clearly identifies the operation and target. The owner/admin prerequisite further sharpens the intended context, and the name/role make sibling confusion 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?

It gives explicit context by requiring owner/admin status and by advising rule-driven grantors to set source_key. It does not explicitly enumerate alternatives such as akb_revoke, but for a straightforward grant operation the use case is clear.

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

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

With no annotations, the description carries the behavioral disclosure burden and does so well: it states the traversal strategy (BFS), the two graph scopes (centered subgraph vs full vault graph), and the returned element types (nodes and edges). It stops short of describing output shape or pagination, but the essentials 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, front-loaded with the core resource and action, and free of filler. Every clause adds useful information about graph scope or traversal behavior.

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

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

There is no output schema, but the description covers the return shape at a high level (nodes for documents/tables/files and edges for relations), plus both invocation modes. It is complete enough for an optional-parameter retrieval tool, though it omits behavior when neither `uri` nor `vault` is provided.

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 parameters are already documented. The description reinforces the `uri`/`vault` mode distinction but does not add material meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the resource (same-vault knowledge graph) and the action (get), enumerating node types and edge meaning. It does not explicitly contrast with sibling graph-adjacent tools like akb_relations or akb_browse, so it misses the top score for sibling differentiation.

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 explicit within-tool usage guidance: pass `uri` for a BFS-centered subgraph, or pass `vault` without `uri` for the full vault graph. It also leverages schema text to disambiguate `hops` from `akb_browse.depth`, but it does not discuss when to choose this tool over alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It covers replacement safety ('writes nothing if the scope exceeds max_replacements'), the three mutually exclusive response shapes, the returned_*/total_*/truncated fields, and the truncation object. This is unusually complete for a tool with no annotation metadata.

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 dense but well organized: purpose first, backend nuance second, sibling comparison third, then output modes and truncation behavior. Every sentence earns its place, and the most decision-relevant information is front-loaded.

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 12-parameter tool with no output schema, the description covers the key behaviors an agent needs: exact vs semantic search, file inclusion rules, replacement semantics, response shape selection, and truncation. The schema handles parameter-level details, so nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining how count_only and files_with_matches alter the response shape, and by advising count_only when truncation may hide exact counts. This adds meaningful cross-parameter context even though individual parameter details live in the schema.

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

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

The first sentence states a specific verb and resource: 'Search for exact text or regex patterns across document content.' It explicitly contrasts with akb_search ('Unlike akb_search... this finds exact string matches'), so an agent can distinguish it from the closest sibling without inspecting 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?

The description explicitly names the alternative (akb_search) and gives the selection condition: semantic/meaning-based vs exact string matches. It also provides concrete use cases ('specific terms, URLs, code snippets, version numbers'), making it clear when this tool is appropriate.

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 expected behavior: no-argument calls return an overview, and drill-downs return details and examples. It stops short of describing output format, but the core behavior is clearly communicated.

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, purposeful sentences. The core purpose is front-loaded, followed directly by actionable invocation instructions. 'START HERE' is high-value guidance, not 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?

The tool is simple, the schema already covers topic and vault semantics including the vault-skill edge case, and the description covers invocation modes. The only minor gap is lack of output-presentation detail, but that is not essential for selecting or invoking a help tool.

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

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

Schema coverage is 100%, so the schema already documents both parameters thoroughly. The description echoes the category/tool/workflow distinction that matches the topic parameter, adding slight orientation, but does not need to repeat schema details. 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 help') and resource ('AKB tools and workflows'), making it clear this is a meta/help tool distinct from the operational sibling tools. It also signals its role as the entry point for new AKB users.

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 to invoke it: call with no arguments for an overview, then drill down into categories or specific tools. 'START HERE if you're new to AKB' provides clear selection guidance, and since this is the only help tool, exclusions are unnecessary.

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 bears full responsibility. It states that each entry is a Git commit and describes the content (who, when, why), implying a read-only operation. It does not mention side effects, auth requirements, or error handling, but the core behavior is clear.

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 concise at two sentences. The first sentence states the purpose and content, the second provides actionable guidance linking to a sibling tool. No unnecessary words.

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 the absence of an output schema, the description gives a good overview: each entry is a Git commit with who, when, why. It also mentions using the commit hash with akb_get. However, it lacks details on pagination, ordering, or whether all versions are included.

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 input schema has 100% description coverage, so the baseline is 3. The description adds no additional meaning beyond what is in the schema parameters (uri and limit). It does not explain URI format or limit context, which might be helpful.

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 clearly states the tool's purpose: retrieving version history of a document, including who changed it, when, and why. It distinguishes itself from sibling tools by mentioning the use of commit hashes with akb_get, indicating a specific role.

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

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

The description provides context for usage by linking to akb_get and implying that this tool is for history retrieval. However, it does not explicitly exclude other scenarios or mention alternatives like akb_diff or akb_provenance, which could be used for similar purposes.

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 it delivers: it explains concept-document handling, the special table/file concept case, that existing paths are skipped rather than overwritten, that reserved records are skipped and reported, and that writer role is required. This is substantial behavioral disclosure beyond 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?

The description is dense but every sentence earns its place: purpose, input shape, format, concept-doc behavior, conflict policy, reserved-record behavior, and auth requirement. It is front-loaded with the core purpose and does not repeat schema details.

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 and no output schema, the description is remarkably complete. It covers the input contract, special cases, idempotency behavior, per-record failures, response reporting for reserved items, and auth. An agent has enough 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 coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by explaining that `files` takes the exact map shape akb_export returns, that `format` currently only supports 'okf', and how concept documents map to imports. It doesn't elaborate on `status` or `_vault_skill_ack`, but those are already well described in the schema.

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

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

States a specific verb and resource: 'Import a knowledge bundle into a vault.' It also differentiates itself from siblings by referencing the bundle shape akb_export returns, making clear it is the bulk-import counterpart to export rather than a single-document tool like akb_put.

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

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

Provides clear usage context: the input must be a {path: content} map in the shape akb_export returns, which strongly implies the tool is for importing exported bundles. It also gives a prerequisite (writer role) and describes edge cases. However, it does not explicitly name alternatives like akb_put or state 'use this instead of X,' so it falls just short of full exclusion 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 present, the description carries the behavioral disclosure burden. It clearly states that this creates a relation, restricts source and target to AKB URIs in the same vault, and enumerates valid relation types. However, it does not disclose important behavior such as whether duplicate relations are rejected or replaced, whether relations are directional, or what the response/return value looks like.

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 compact and front-loaded with the core action and purpose. Every sentence earns its place: the operation, constraints, allowed relation types, and a clarifying example are all included without 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?

For a relatively simple create-relation tool with full schema coverage, the description is complete enough for an agent to invoke it correctly. It explains the core behavior, constraints, and typical use cases. The only notable gap is the absence of return-value or post-condition details, but this is not critical given the simplicity of the operation.

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 already documents all parameters with 100% coverage, so the baseline is 3. The description adds useful examples of source/target URIs and relation types, but it does not meaningfully enrich the semantics of individual parameters 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?

The description names a specific action ('Create a relation'), a concrete resource domain ('between any two resources: documents, tables, files'), and the supported relation types. This cleanly distinguishes it from read-only sibling tools like akb_relations and the inverse operation akb_unlink.

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 makes the intended use clear with concrete examples, such as linking a design doc to its data table or attaching a diagram to a spec. It does not explicitly state when not to use it or name alternatives, but the context is sufficiently clear for an agent to decide when this is the right 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?

Discloses that response is slim and explains optional args, but does not explicitly state it is read-only or non-destructive. Since no annotations exist, the description carries full burden; it is adequate but not comprehensive.

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?

Extremely concise and well-structured. First sentence states main action and output, second describes response format, then a clear list of optional args. Every sentence serves a purpose with no 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?

For a list tool, it covers essential behavior: response structure, filtering, pagination, and archived inclusion. However, it could be more complete by mentioning when to use this tool over siblings like akb_search or akb_browse, given the large sibling set.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal value: for filter, it gives a usage example, but limit/offset and include_archived repeat schema info. Does not expand on parameter constraints or behavior.

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?

Clearly states it lists accessible vaults with name and description, and specifies output format. However, it does not explicitly differentiate from sibling tools like akb_vault_info or akb_vault_members, which could cause confusion when to use this tool over others.

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

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

Provides usage guidance for parameters (filter, pagination, include_archived) with examples like filter='finance'. But no guidance on when to use this tool vs alternatives (e.g., for detailed vault info use akb_vault_info), nor any exclusions or prerequisites.

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 transparency burden and does this well: it discloses redirect behavior for the old URI, rewriting of graph links/publications, git-history preservation, and unchanged title. It stops short of mentioning permissions, failure modes, or return value, which would make it fully transparent.

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?

Each of the four sentences adds distinct value: what moves, what is preserved, redirect/rewrite behavior, and the constraint plus alternative tool. The critical constraints are front-loaded before the pointer to akb_update.

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

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

For a mutation tool with no annotations and no output schema, the description covers the essential call-time decisions and side effects well. It does not describe the response format or authorization requirement, but all selection and invocation criteria are substantially present.

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 the key constraint that collection and slug are optional yet at least one must change. It also adds meaning to slug ('filename base'), complementing the schema's basic descriptions.

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

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

States a specific verb-resource pair ('Move or rename a document') and the exact dimensions that change (collection and/or slug), immediately setting it apart from content-editing tools. It explicitly distinguishes itself from akb_update by noting the title is unchanged.

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 when-to-use rule: change a document's collection/slug while preserving identity and history. It also provides a when-not-to-use direction by pointing at akb_update for title changes, plus the precondition that at least one of collection/slug must change.

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 of explaining behavior. It usefully discloses the return categories and scoping ('visible same-vault relations'), but does not clarify whether the operation has side effects, requires specific permissions, or what the response format looks like. 'Get' implies a read operation, which mitigates some of the ambiguity.

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 a single, well-structured sentence that front-loads the core action and then efficiently enumerates the returned data. Every clause contributes meaningful information, with no redundancy or 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 simple one-parameter read tool with no output schema and no annotations, the description covers the essential purpose and return scope well. It could be more complete by stating explicit use alternatives or permission implications, but nothing critical is missing for an agent to 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?

The schema already documents the only parameter 'uri' at 100% coverage, so the baseline is 3. The description adds no additional detail about URI format, required scheme, or accepted value patterns beyond what the schema 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?

The description provides a clear active verb ('Get') and resource ('document'), and enumerates the specific provenance information returned: creator, timestamp, extracted entities, and visible same-vault relations. It does not explicitly name sibling tools to contrast against, but the described content is specific enough to differentiate it from generic retrieval tools like akb_get, akb_relations, or akb_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?

The intended use is implied: call this tool when you need provenance metadata for a document. However, the description does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or preconditions.

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 burden. It discloses the return shape (same as akb_publish) but omits safety traits, side effects, pagination, or error behavior. The 'list' verb implies read-only, but this is not explicit. Score reflects minimal but non-contradictory transparency.

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

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

Two sentences, no filler. The first sentence states the core action, the second adds return value detail. Every word earns its place; highly efficient and front-loaded.

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 list tool without output schema, the description provides return shape context but lacks details on ordering, pagination, error handling, or the optional filter. Adequate but leaves gaps for a production tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no meaning beyond schema: it does not elaborate on 'vault' or the 'resource_type' filter. The return shape note is useful but not parameter-specific.

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 clearly states the tool lists every publication in a vault, using a specific verb ('List') and resource ('publications'). It distinguishes itself from sibling tools like akb_publish (creates) or akb_unpublish (removes) by focusing on reading, with no ambiguity.

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 guidance on when to use this tool versus alternatives (e.g., akb_search or akb_publication_snapshot). The description only states what it does, without context about prerequisites, exclusions, or comparative advantages.

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 of behavioral disclosure. It does explain the core side effects: freezing the result to S3, flipping the mode to snapshot, and caching behavior for subsequent visits. However, it omits details about reversibility, potential data loss, permissions required, or error conditions (e.g., if the publication is not a table_query publication), leaving some behavioral ambiguity.

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 concise and front-loaded, with two sentences that convey the core action, the identification method, and the return value without any filler. Every sentence earns its place, and the structure is efficient.

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

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

The description covers the essential aspects: the operation, the mode change, the caching behavior, identification, and the return type. It could mention prerequisites (e.g., the publication must be a table_query publication) and whether the operation is reversible, but for a tool with no output schema and moderate complexity, it is largely 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?

The input schema already has 100% coverage, so the baseline is 3. The description adds value by clarifying that slug alone is sufficient and that the vault is resolved from the publication, which is not obvious from the schema's simple 'Publication slug'. This extra context makes the parameter semantics clearer, warranting a 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?

The description clearly states the tool's purpose: it freezes a table_query publication's current result to S3 and flips its mode to 'snapshot', which differentiates it from siblings like akb_publish and akb_unpublish. The verb 'freeze' and resource 'publication' are specific, and it clarifies that the vault is resolved from the slug, eliminating ambiguity about required parameters.

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

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

The description provides clear context on when to use the tool: when you want a publication to serve a cached result instead of re-querying, and that it applies specifically to table_query publications. It notes that the vault is derived from the publication, but does not explicitly mention alternatives or when not to use it (e.g., for non-table_query publications), so it falls 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 present, the description carries the full burden and covers the two most operationally significant behaviors: the created share is publicly viewable with no authentication, and the return contract is a canonical publication dict where slug is the only identifier needed and share_url is always absolute. It could disclose idempotency-on-republish or caller permissions, but the core side effect is clearly stated.

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 sentences, front-loaded with the action, then parameter-selection logic, then return-value guidance. Every sentence earns its place with zero filler and no restatement of 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 13-parameter, three-mode tool with no output schema and no annotations, the description covers the highest-risk decision (parameter selection per resource_type) and the essentials of the return contract (slug, share_url). Remaining details like expiry/password effects and re-publishing behavior are left to the schema or implicit, which is acceptable at this complexity level.

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 cross-parameter meaning that per-parameter schema entries cannot convey: resource_type conditionally determines which of uri vs query_sql+vault must be supplied, and vault is inferred from the URI for doc/file yet must be passed explicitly for table_query. The slug guidance also reduces the agent's post-call burden.

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

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

The description opens with a specific verb-action pairing — 'Create a public, no-auth share URL' — and enumerates the three publishable resource kinds (document, file, table query). The 'no-auth share URL' framing clearly differentiates it from near-siblings like akb_set_public or the publication-management tools akb_unpublish and akb_publications.

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

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

It states exactly when to call it (whenever a public, unauthenticated share is needed) and how to structure the call by resource type: document/file → uri; table_query → query_sql + vault, with a conditional note on query_vault_names for multi-vault queries. It stops short of explicitly naming excluded alternatives or when-not-to-use conditions, so not 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?

It usefully discloses that documents are 'automatically chunked and indexed for semantic search' and that the response carries a canonical URI. However, with no annotations present, the description does not cover other important behavioral traits like overwrite behavior for an existing URI, required permissions, or whether the vault/collection must already exist.

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 sentences with no filler: the purpose is first, followed by the canonical response behavior, then the indexing side effect. Every sentence earns its place.

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

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

For a 15-parameter tool with no annotations and no output schema, the description covers key behavioral outcomes but leaves gaps around failure modes, duplicate-document handling, and prerequisites for vault/collection targets. The rich input schema compensates for parameter understanding, but runtime behavior is only partially disclosed.

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 baseline is 3 even without parameter guidance in the tool description. The description reinforces the URI-return behavior which complements the schema, but it adds no parameter-specific meaning beyond what the schema already documents.

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 specific verb and resource ('Store a new document') and clarifies where the document lands via canonical URI forms. It is clear, but it does not explicitly distinguish this tool from siblings like akb_put_file or akb_update beyond the word 'new'.

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 explains what to do with the returned URI, but does not state when to prefer this tool over alternatives such as akb_update, akb_edit, or akb_put_file. No exclusions or conditions are given, leaving tool selection largely 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 exist, so the description carries the full disclosure burden — and it delivers: it reveals the S3 backing, the exact response contract (`akb://{vault}/coll/{collection}/file/{uuid}` vs `akb://{vault}/file/{uuid}`), the recommended follow-up tools (akb_get_file / akb_update_file / akb_delete_file), and MIME auto-detection behavior. It falls short only on edge behaviors like overwrite semantics or permission prerequisites.

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 sentences with zero filler. The primary action is front-loaded in sentence one, the response contract and chaining strategy are compactly packed into sentence two, and the MIME behavior closes it out. Every sentence earns its place.

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

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

For a 7-parameter upload tool with no output schema and no annotations, the description is unusually complete: it covers purpose, selection criteria, return contract, follow-up routing, and a default-behavior override. The only notable gaps are preconditions (vault existence, write access) and whether re-uploading to the same location overwrites — minor for a tool whose params are already fully documented in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description elevates this by illustrating how the parent/vault/collection parameters map to the two possible canonical uri shapes, which the individual schema entries don't tie together. The MIME sentence partly duplicates the mime_type parameter description, so the net added value is moderate rather than large.

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 specific verb and resource: 'Upload a local file to a vault's file storage (S3-backed).' It distinguishes itself from the closest sibling akb_put by targeting 'any binary content too large for akb_put,' so an agent can tell them apart 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?

'Use for PDFs, images, datasets, or any binary content too large for akb_put' explicitly names the alternative tool and the condition that selects this one. The 'too large' qualifier implies the exclusion case (small or textual content belongs in akb_put), giving clear when-to-use 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 provided, the description carries the full behavioral burden. It discloses key traits: images are immutable, the upload creates a hidden attachment rather than a standalone File, the returned URL is stable, and a failed document write requires cleanup via akb_discard_image. It does not mention auth or rate limits, but for this tool the operational consequences are well covered.

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

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

The description is front-loaded with the core purpose and return values, then moves through usage alternatives, behavioral caveats, and failure handling. Every sentence earns its place, and the prose is dense without being bloated.

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 correctly explains the return: 'a stable `/api/assets/{uuid}` URL and a ready-to-paste `markdown` image expression.' It also covers prerequisites, alternatives, immutability, browse/search visibility, and cleanup on failure. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters in detail. The description adds useful context around supported file types, the 10 MiB limit, and the return value, but does not materially enrich parameter meaning beyond what the schema already states. 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 the specific action and resource: 'Upload a local PNG, JPEG, GIF, or WebP ... for inline use in an AKB Markdown document.' It also distinguishes itself from akb_put_file by clarifying this creates 'a hidden document attachment, not a standalone File,' so an agent can tell the two upload tools apart immediately.

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

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

Provides explicit routing guidance: use akb_put for a new document, prefer akb_edit for an existing document, and warns that akb_update 'must never receive only an image fragment.' It also names akb_put_file as the alternative when browse/search visibility is needed, and gives the failure fallback of calling akb_discard_image. This is strong 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?

No annotations are provided, so the description carries the behavioral burden. It does disclose the scope (same-vault only), the cross-type nature of results, and the explicit/implicit classification per row. It doesn't mention auth needs, rate limits, or potential absence of results, which leaves some transparency gap for a read 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?

Three short sentences, front-loaded with the core purpose, then output details, then the edge-classification nuance. Every sentence contributes value with no filler or repetition.

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

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

For a read-only filtering tool of this complexity, the description covers what the tool returns, the scope, and the key distinction between explicit and implicit links. With no output schema, the description partially explains the return shape. It is complete enough for an agent to call the tool correctly, though a brief note on when no relations are expected would make it 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?

Schema coverage is 67%, so the schema already documents uri, type, and direction. The description adds useful context about resource categories ('document, table, or file') but does not explain the semantics of each relation type or direction values beyond what the schema provides. Baseline 3 is appropriate given the moderate coverage.

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

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

The description opens with a specific verb and resource scope ('Get relations for any resource (document, table, or file)') and adds differentiating detail: same-vault cross-type connections and explicit vs implicit edges. This sets it apart from siblings like akb_graph and akb_provenance.

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?

Usage is implied by the description: call this when you need relations for a resource. However, it does not explicitly state when to prefer this tool over related siblings (e.g., akb_graph, akb_provenance) or when not to use 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 provided, the description carries the burden of behavioral disclosure. It reveals the permission requirement, the destructive all-basis behavior when source_key is omitted, and the nuanced 'may downgrade rather than remove' outcome. This is meaningful behavioral context beyond the raw 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?

Two dense sentences deliver the action, permission requirement, and behavioral branch without filler. The most important facts are front-loaded and every phrase 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?

Given rich schema descriptions for all five parameters, the description's permission and mode distinction cover the essential non-schema context. A response/return-value note would help, but the tool remains safely callable with the information provided.

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 baseline is 3. The description rephrases the source_key semantics already present in the schema without adding new parameter-level details; it adds operational context rather than parameter meaning.

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 action—'Revoke a user's vault access'—and immediately clarifies the two distinct behaviors depending on whether source_key is present. This makes it easy to distinguish from inverse and ownership tools like akb_grant and akb_transfer_ownership.

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 clear operational context: owner/admin is required, and the tool revokes vault access. It does not explicitly name alternatives or when-not-to-use cases, but the coarse-vs-fine-grained revocation distinction is enough for an agent to select it appropriately.

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, and it succeeds admirably. It discloses that total_matches is not a corpus-wide count, explains what truncated=true and degraded=true mean, warns that degraded results are not genuine zero-matches, and names degradation_reason as the cause source. It also clarifies which returned fields affect ranking and which do not.

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?

Although the description is long, every sentence earns its place: retrieval mechanism, sibling distinction, result semantics, truncation behavior, and degradation behavior. It is front-loaded with the core purpose and uses precise, dense phrasing without fluff or repetition.

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

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

With no output schema, the description fully explains the response semantics an agent needs: returned fields, total_matches' true meaning, truncation, and degradation. It also tells the agent how to proceed after retrieving URIs and when to fall back to akb_grep. For a complex hybrid search tool with eight parameters and no annotation coverage, this is a complete and reliably actionable definition.

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 high (88%), which sets a strong baseline. The description adds useful parameter-level nuance beyond the schema's 'Natural language search query' label by noting the query handles both natural-language questions and short keyword queries. It does not elaborate on the remaining filters, but their schema descriptions are already explicit, so no major gap exists.

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 specific action and resource ('Search documents with hybrid retrieval') and explains the retrieval mechanism in precise terms. It actively distinguishes itself from akb_grep by contrasting hybrid semantic/keyword search with exact string/regex matching, so an agent can separate it from sibling tools 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 explicit when-to-use guidance: use this tool for natural-language and short keyword queries, and prefer akb_grep for exact string/regex matches. It also provides concrete fallback paths for truncated and degraded results, telling the agent exactly when to switch to akb_grep with count_only=true or a literal search.

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 provided, so description carries full burden. It mentions search fields but lacks details on result format, case sensitivity, or match behavior, adding only basic info beyond 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?

Two sentences, no redundancy, front-loaded with purpose and usage. Every sentence is informative.

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?

Sufficient for a simple search tool, but missing output schema details like return format. Could hint at results (e.g., user IDs) for completeness.

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

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

The description expands the query parameter's meaning beyond the schema (adding 'username, display name') but doesn't elaborate on limit. For 50% schema coverage, it compensates partially.

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 clearly states this tool searches for users by username, display name, or email, and distinguishes it from sibling tools like akb_grant and akb_search.

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 the tool: before granting vault access, providing clear context and implying when not to use alternatives.

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

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

With no annotations, the description carries the burden of behavioral disclosure and does state the ownership restriction plus the precise semantics of each access level. It does not mention reversibility, effects on existing member permissions, or return/error behavior, which is a meaningful gap for a sensitive mutation.

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 dense sentence that front-loads the verb and resource, then packs ownership and enum semantics into a compact, readable format. 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 simple three-parameter setter, the definition supplies the essential context: action, ownership prerequisite, and level consequences, while the schema fully covers parameters including the ack token. Absence of an output schema is acceptable for this kind of mutation, though a note on side effects would push it higher.

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

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

Schema coverage is 100%, but the description enriches the level parameter by mapping enum values to concrete behavior ('none'=private, 'reader'=public read, 'writer'=public read+write). The vault and ack parameters are adequately documented by the schema itself.

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 action on a specific resource ('Set vault public access level') and enumerates the three level meanings. It does not explicitly reference sibling tools like akb_grant or akb_publish, so differentiation is implicit rather than explicit.

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?

Adds a clear prerequisite ('Owner only') and defines each level, making it evident this sets vault-wide public access rather than per-user grants. It doesn't spell out when-not-to-use or name alternatives such as akb_grant or akb_revoke.

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 present, the description carries the full safety and behavior burden, and it does a solid job: it discloses that tables are real PostgreSQL tables, that SELECT needs a reader role while writes need a writer role, and that results are never silently truncated so unbounded SELECTs can return very large payloads. It does not fully specify behavior around DDL support, transaction/commit semantics, or the exact result shape, which prevents a perfect score.

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

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

The description is front-loaded with the core purpose, then proceeds logically through naming, cross-vault usage, roles, and the LIMIT warning. Every sentence earns its place, and no information is redundant with the schema. Despite covering multiple important caveats, it is compact and easy to parse.

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?

Considering the moderate complexity of a SQL execution tool with auth, cross-vault, and large-result concerns, the description covers the most operationally critical details well. The main gaps are that it never states whether DDL statements are supported (and if not, which sibling tool to use) and it does not describe the structure of the returned result set, which matters more because there is no 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?

The input schema already documents all four parameters, so the baseline is 3, but the description adds meaningful semantics on top: it explains that table names are auto-resolved to vault tables and introduces the sales__pipeline-style prefix convention for the vaults/vault parameters. It also reinforces the LIMIT guidance already present in the sql parameter description. The _vault_skill_ack parameter is not further elaborated beyond the schema, but it is already clearly described there.

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 clear verb and resource: 'Execute SQL on vault tables.' It further specifies that these are real PostgreSQL tables and explains table-name resolution, which distinguishes this tool from sibling table-management tools like akb_create_table and akb_drop_table. An agent can immediately tell this is for running queries/DML against vault data rather than for more general data access.

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

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

The description provides strong practical context: when to use the vaults parameter, how to prefix table names for cross-vault queries, role requirements for SELECT vs. INSERT/UPDATE/DELETE, and a clear LIMIT instruction to avoid oversized responses. However, it does not explicitly name sibling alternatives or state when not to use this tool (e.g., for DDL or object-level access), 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?

No annotations exist, so the description carries the full disclosure burden. It does add one meaningful behavioral fact — the permission requirement (current owner or system admin). However, it does not disclose what happens to the previous owner after transfer, whether the new owner must already be a vault member, or whether the operation is reversible, all of which are material for a mutation 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 sentences totaling roughly 15 words with the core action front-loaded ('Transfer vault ownership to another user') and the authorization note in a short second sentence. Zero filler; every word 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 simple two-required-parameter mutation with no output schema and no annotations, the description covers the basic what and who. But it omits the post-transfer state of the previous owner, any prerequisites for the new owner, and the return value — gaps an agent would need to resolve before confidently invoking the tool.

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

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

Schema description coverage is 100% (vault = 'Vault name', new_owner = 'Username of the new owner'), so the baseline is 3. The description adds no extra parameter detail beyond what the schema already provides, such as format, lookup behavior, or constraints on the username.

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?

Description states a specific verb (Transfer), resource (vault ownership), and destination (another user) in a single crisp sentence. This clearly distinguishes the tool from access-management siblings like akb_grant, akb_revoke, and akb_vault_members, which operate on permissions rather than ownership.

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 conveys the authorization context ('The current owner or a system admin can do this'), which tells the agent when the call is permitted. However, it offers no explicit guidance on when to prefer this over related siblings such as akb_grant or akb_vault_members, nor does it state when not to use 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 provided, the description carries the full burden of explaining this destructive operation. It usefully discloses that omitting relation removes all explicit relations and that implicit relations are managed elsewhere, but it doesn't mention permission requirements, reversibility, what happens if no relation exists, or the acknowledgement flow.

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 sentences, each adding distinct information: the core action, how implicit relations are handled, and the wildcard behavior. The primary verb and resource are front-loaded with no filler or repetition.

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

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

For a low-complexity tool with a richly documented schema, the description covers the core semantics and the main ambiguity (explicit vs implicit relations). It omits return/error behavior and safety context, but the operation is straightforward and no output schema is expected.

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 four parameters including the relation enum and the ack parameter. The description adds no parameter-level detail beyond what the input schema states; the 'omit relation' behavior is already captured in the relation property description.

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 specific verb ('Remove'), names the exact resource (explicit same-vault relation between two resources), and immediately distinguishes explicit from implicit relations. This clearly differentiates it from relation-creation or editing tools like akb_link and akb_edit without needing schema inspection.

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

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

It gives clear guidance on when this tool applies: only explicit relations, and it notes the alternative path for implicit relations via editing the source document. However, it doesn't explicitly name sibling tools or enumerate edge cases where another operation is preferable, so it stops short of a full routing statement.

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 supplies the behavioral context: the operation is destructive, uri mode is broader than slug mode, table_query publications behave differently, and the return shape is {deleted: N}. It doesn't discuss irreversibility or permissions, but the removal semantics are clearly stated.

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 with no filler. The action, parameter choice, edge case, and return value are all packed efficiently, with the core instruction front-loaded.

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

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

The description includes the return format, both invocation modes, and the exceptional table_query case, which is sufficient for normal use. It could be slightly more explicit that exactly one of slug or uri is expected, but 'Pass slug ... OR uri' conveys this reasonably.

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 already covers all parameters, so the baseline is 3. The description contributes extra meaning by explaining the OR relationship, the resource-wide effect of uri, and the table_query no-URI edge case.

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 and object, 'Remove publication(s)', and immediately distinguishes two scopes: slug for one specific publication, uri for all publications of a resource. This makes the tool's purpose obvious and separates it from sibling publication 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?

It gives explicit conditions for choosing slug vs. uri, including the table_query exception ('remove them by slug'). It does not name alternative sibling tools, but the in-tool guidance is unambiguous and practical.

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 disclosure burden. It clearly warns that `content` replaces the entire Markdown body and should never receive a partial fragment, which is the most important behavioral trap. It does not disclose commit/versioning behavior or failure modes, so it is strong but not exhaustive.

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 the purpose, and every sentence carries operational weight. There is no filler or repetition of schema details.

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

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

For a mutation tool with 15 parameters, no annotations, and no output schema, the description covers the core usage pitfalls and sibling routing well. It does not explain what the operation returns or the optimistic-concurrency pins, but those are partially described in the schema, so the definition is strong but not fully comprehensive.

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 80%, so most parameter semantics already exist in the schema. The description adds real value by explaining the partial-update model ('Only provide fields you want to change') and by clarifying that `content` is a complete replacement, not an incremental edit.

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 clear verb and resource: 'Update an existing document'. It also distinguishes itself from the sibling akb_edit by noting that akb_edit is for targeted inline insertion or replacement, which helps an agent pick the right 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?

It gives concrete usage guidance: only provide fields to change, and use akb_edit for targeted inline edits instead. This explicitly routes the agent to the correct alternative, which is exactly what this dimension asks for.

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 supply a safety or side-effect profile, the description carries this burden and does so well: the local file is hashed before transfer, identical content is skipped, URI is preserved, and stale writes are rejected with HTTP 409 rather than overwriting. This makes the tool's mutation semantics and failure mode transparent.

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 sentences, front-loaded with the core operation, then behavioral and concurrency guidance. Every sentence carries distinct information and there is 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 six-parameter mutating tool with no output schema and no annotations, the description is nearly complete: it explains the operation, skip behavior, and 409 conflict handling. It does not describe the return value or mention permissions, but these are secondary to correct invocation and the schema covers all parameters.

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

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

Schema coverage is 100% and each parameter already has a solid description, so the description does not need to repeat definitions. It adds value by explaining the workflow rationale behind expected_content_hash and expected_version (concurrency protection from akb_get_file) and by noting that identical content is skipped, which clarifies the role of file_path.

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

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

The description names a concrete action and resource: 'Replace the bytes of an existing vault file while preserving its URI.' This distinguishes it from file creation or URI-changing tools like akb_put_file and akb_move, so an agent can tell what it is for 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?

It gives clear context by stressing the target is an existing file whose URI is preserved. It also instructs when to use the optimistic-concurrency parameters ('Pass expected_content_hash and/or expected_version from akb_get_file to reject stale writes'), but it does not explicitly name sibling tools for alternative cases such as creating a new file or updating metadata.

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 full burden. It indicates a read operation returning counts and last activity, but does not explicitly state it is read-only, required permissions, or behavior for missing vaults. This is adequate but leaves minor gaps.

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 a single sentence that efficiently lists key outputs without unnecessary words. It is front-loaded with the core purpose and specific details.

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 the tool's simplicity (one parameter, no output schema), the description is fairly complete, listing returned fields. It lacks information on error handling or permissions, but for an info retrieval tool, this is sufficient.

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 description coverage is 100% for the single 'vault' parameter. The description adds no additional semantic information about the parameter beyond what the schema already provides, which is baseline acceptable.

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 clearly states the tool retrieves detailed vault information, listing specific data points like owner, member count, and file counts. This distinguishes it from sibling tools such as akb_list_vaults (which lists vaults without details) and akb_vault_members (focused solely on members).

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 usage for obtaining detailed stats on a single vault, contrasted with siblings like akb_list_vaults for overview. However, it does not explicitly state when not to use this tool or mention alternatives for member-specific or activity-specific queries.

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 provided, so description carries full burden. It explicitly states it is a read-only listing operation with roles, which is transparent. It does not disclose permissions or pagination, but for a simple list tool, this is 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?

Single sentence, no redundant words, front-loaded with action and resource. Highly efficient.

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 the tool's simplicity (single parameter, no output schema, straightforward purpose), the description fully covers necessary context. Sibling tools provide alternatives but do not require additional detail here.

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% (vault parameter described as 'Vault name'). Description adds no new semantics beyond restating that it lists members for a vault. Baseline of 3 is appropriate.

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

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

Description clearly states the action 'list' and the resource 'members of a vault', specifying the roles (owner, admin, writer, reader). This directly distinguishes it from sibling tools like akb_list_vaults (lists vaults) and akb_vault_info (vault metadata).

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?

Usage is implied (when you need to list members of a vault), but no explicit guidance on when not to use or alternatives. For example, adding members would require akb_grant, and listing vaults would use akb_list_vaults, but these are not mentioned.

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 implies a read operation without side effects, but does not disclose any additional behavioral traits. For a simple profile check, this is adequate but minimal.

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, concise sentence with an action verb and context. Perfectly front-loaded and efficient.

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 zero parameters and no output schema, the description fully captures the tool's behavior and use case. No gaps remain.

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?

No parameters, so schema coverage is 100%. The description adds value by enumerating the profile fields returned, providing meaning beyond the empty schema.

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

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

The description clearly states the tool gets your current profile and lists specific fields (username, email, display name, role). This is distinct from sibling tools like akb_search_users or akb_grant, which deal with other users or permissions.

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 'Use this to check who you are authenticated as,' providing clear context. While it doesn't list exclusions or alternatives, the purpose is self-contained and obvious.

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