akb

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v2.0.13
Disambiguation5/5
Each tool has a clearly distinct purpose, with no overlapping or ambiguous functionality. Even similar tools like akb_search and akb_grep are explicitly differentiated by search type.
Naming Consistency5/5
All tools follow the consistent 'akb_' prefix with a verb_noun pattern (e.g., akb_create_vault, akb_get_file). The naming is predictable and easy to navigate.
Tool Count4/5
43 tools is on the higher side, but each tool addresses a specific operation within the comprehensive AKB system. The count is justified by the extensive feature set.
Completeness5/5
The tool suite covers the full lifecycle of vaults, documents, tables, and files, including creation, retrieval, update, deletion, search, browsing, version control, permissions, publications, and graph operations. No obvious gaps are present.
Average 4.1/5 across 43 of 43 tools scored. Lowest: 3.1/5.
See the Tool Scores section below for per-tool breakdowns.
- 6 of 7 community issues answered or closed in the last 6 months
- 483 commits in the last 12 weeks
- Last stable release on August 12, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description must cover behavior. It states removal but does not disclose permanence, error handling (e.g., missing relation), or side effects. Agent lacks key safety info.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded, no wasted words. Efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is adequate for basic understanding but lacks return value, error cases, and prerequisites. Slightly under-specified for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all params; description adds value by explaining the optional 'relation' parameter behavior (omit to remove all). Clear and useful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Remove' and specific resource 'relation between two resources'. Distinguishes from akb_link. Could be more precise about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like akb_relations or akb_link. No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description gives only basic behavioral context (mutation, partial update). It does not disclose concurrency control details (OCC pins), side effects, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short, clear sentences with no unnecessary words. It front-loads the core action and key usage rule.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (12 parameters, concurrency controls), the description is too brief. It omits explanation of commit message, OCC pins, and the relationship with similar tools like 'akb_edit'. The lack of output schema also requires more behavioral description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, so most parameters already have descriptions. The description adds the helpful principle of partial updates, but does not elaborate on the optional OCC or content hash parameters, which are important for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update an existing document') and resource, but does not distinguish it from the sibling tool 'akb_edit', which likely has similar semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'Only provide fields you want to change' implies partial update behavior, but there is no explicit guidance on when to use this tool versus alternatives like 'akb_edit' or 'akb_put'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must cover behavioral aspects. It only states 'delete' without disclosing irreversibility, authorization needs, or potential side effects. Minimal 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is highly concise and front-loaded with the action. Every word is necessary and contributes to clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter, the description covers the basic functionality. However, missing behavioral details like irreversibility or required permissions reduce completeness slightly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already describes the URI format. The description adds 'by its URI' which is redundant but reinforces the purpose. Baseline 3 due to high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete) and resource (file), and specifies the method (by URI). It effectively differentiates from sibling tools like akb_delete_vault or generic deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like akb_delete. No prerequisites, permissions, or context for invoking the tool are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It implies a read-only operation but does not mention required permissions, side effects, rate limits, or whether the tool is safe to call repeatedly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The purpose is front-loaded, and the description immediately conveys the tool's value with concrete examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no output schema, and no annotations, the description is minimally adequate. It explains what relations are but omits details like output format, pagination, or behavior when no relations exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 67% of parameters with descriptions; the 'direction' parameter lacks a description. The tool description adds no detail about parameter values or usage beyond the schema, missing an opportunity to clarify the 'direction' and 'type' parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves relations for resources and explicitly lists resource types (document, table, file) and connection types (doc→table, etc.), making its purpose distinct from sibling tools like akb_link or akb_graph.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks explicit guidance on when to use this tool versus alternatives like akb_graph or akb_provenance. It does not mention prerequisites, when not to use it, or specific use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states 'makes it read-only' and owner restriction, but omits details on reversibility, side effects, or permission requirements beyond ownership.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, front-loaded with core action and effect.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with one param and no output schema; description is adequate but lacks detail on reversibility or post-archive state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with basic description; tool description adds no extra meaning beyond 'Vault name', meeting baseline but not adding value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (Archive), resource (vault), and effect (makes it read-only), distinguishing it from sibling tools like delete or create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions owner-only constraint but lacks explicit guidance on when to use this tool versus alternatives like deleting or changing permissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that deletion affects three systems (Git, search index, knowledge graph), which adds transparency. However, it does not mention whether the operation is reversible, requires permissions, or has cascading effects on related data. This is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that conveys all necessary information without extraneous words. It is front-loaded and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema) and the presence of sibling delete tools, the description covers the core behavior and its effects. It could mention that deletion is permanent or irreversible, but overall it provides sufficient context for an agent to understand the tool's operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the single parameter 'uri' is described in the schema as 'Document URI'. The description adds no additional meaning for the parameter beyond what the schema provides, so it earns a baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and the resource 'document', specifying that it removes from Git, search index, and knowledge graph. This distinguishes it from sibling tools that delete collections, files, or vaults.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., akb_forget, akb_unlink, akb_delete_file). The description does not include context about prerequisites, when not to use, or situations where other tools are more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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 only mentions the access requirement but fails to disclose behavioral traits such as reversibility, side effects, or success/failure indicators. For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both essential: first states the action, the second adds a critical condition. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should explain the result of the operation. It lacks any indication of success confirmation, error conditions, or post-revoke state. The tool is a mutation but fails to provide sufficient context 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, and the tool description adds no extra meaning beyond what is already in the schema. The baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'revoke' and the resource 'vault access', making the purpose unambiguous. It distinguishes from related siblings like akb_grant and 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use (revoking vault access) and a prerequisite (must be owner or admin). However, it does not explicitly mention when not to use or provide alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states the action and owner constraint, omitting side effects (e.g., whether the previous owner becomes a member) or reversibility, which is insufficient 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, no redundant words, and all information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity of the tool (two parameters, no output schema), the basic purpose and prerequisite are covered. However, behavioral details are lacking, and the description does not fully compensate for missing annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear parameter descriptions ('Vault name', 'Username of the new owner'). The tool description adds no additional semantic value beyond what the schema already provides, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (transfer) and the resource (vault ownership), distinguishing it from sibling tools like akb_create_vault or akb_delete_vault. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a clear prerequisite ('Only the current owner can do this'), guiding the agent on who can invoke the tool. However, it does not mention alternatives 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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It states the operation uses ALTER TABLE DDL and requires admin role, providing some transparency about permissions and DDL execution. However, it does not warn about the destructive nature of dropping/renaming columns or mention the preflight check behavior for unique keys, leaving gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 13 words, front-loaded with the verb and object. It is concise and free of unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex 8-parameter tool with nested objects, no output schema, and no annotations. The description covers only column modifications, completely omitting the ability to add/drop indexes and unique keys. It also lacks warnings about potential data loss or side effects, making it incomplete for the tool's actual scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 minimal value beyond the schema by mentioning column modifications but omitting the index and unique-key parameters, which are well-documented in the schema itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool modifies a table's schema with specific actions (add, remove, rename columns) via ALTER TABLE DDL. This distinguishes it from siblings like akb_create_table and akb_drop_table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use when modifying an existing table's schema. It also provides a key precondition (requires admin role). It does not explicitly name alternatives or exclusions, but the verb 'alter' implies existing tables, making the usage intent unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the output structure (creator, time, entities) but does not mention side effects, authorization needs, or that it is a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose, no extraneous content. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description hints at return structure (who, when, entities). It is mostly complete for a simple one-parameter tool, but could explicitly state it is a read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers the single parameter 'uri' with a description. The tool description adds no additional parameter-level details beyond what the schema already provides. Baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'get', resource 'provenance for a document', and details what provenance includes (creator, time, entities). Distinguishes from siblings as the only provenance-specific tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage context (getting provenance) but provides no alternatives or when-not-to-use guidance. No explicit exclusions or comparisons to similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the prerequisite (owner/admin) and the action, but lacks details about effects, error cases, or immediate outcomes beyond stating the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences, front-loaded with the action, and no redundant information. Every word is necessary and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three required parameters, no output schema, and no annotations, the description sufficiently defines the operation and prerequisite but omits details about return values, error handling, or success criteria, leaving some gaps for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The description does not add meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Grant vault access'), the target resource ('vault access to a user'), and the prerequisite ('must be owner or admin'), which distinguishes it from siblings like akb_revoke.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage context by specifying the prerequisite (owner/admin role) but does not explicitly mention when to use this tool vs alternatives (e.g., akb_revoke) 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states the tool creates a relation but does not clarify whether it overwrites existing relations, requires specific permissions, or handles invalid URIs. Key behavioral traits are missing, making it insufficient for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences that front-load the purpose and then provide specific details (relation types, example). Every sentence adds value without redundancy or unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and sibling tools that include akb_unlink and akb_relations, the description covers the core purpose adequately. However, it does not explain what the tool returns on success or how errors are handled, leaving some gaps for an agent to fully understand the invocation context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has full coverage (100%), but the description adds significant meaning: it explains that source and target are AKB URIs, lists all relation types from the enum, and provides usage examples. This goes beyond the schema by offering contextual guidance on how to use each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a relation between two resources, lists all relation types, and provides an example by mentioning linking a design doc to a data table. This distinguishes it from sibling tools like akb_unlink, making the purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use the tool (creating a relation between any two resources) and provides examples of usage (e.g., link a design doc to its data table). However, it does not explicitly exclude cases or mention alternatives like akb_relations for viewing existing relations, which prevents a higher score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description covers authorization ('Owner only') and level definitions, but lacks details on side effects, reversibility, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with a three-item definition list. Every part is essential; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple two-parameter tool with no output schema. Could mention expected return value (e.g., success/failure).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage. Description adds meaning to 'level' by explaining enum values, which goes beyond the schema's 'Public access level'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Set' with resource 'vault public access level' and explicit enum meanings. Distinguishes from sibling tools like akb_grant or akb_revoke.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States 'Owner only' as a constraint, but does not explicitly indicate when to use this tool vs 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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. Discloses key behaviors: permanence ('Cannot be undone'), permission requirement ('Requires admin role'), and scope ('all its rows'). However, does not mention potential effects on related objects (e.g., dependencies).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: two sentences, no redundant words. Front-loaded with the core purpose. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with one parameter and no output schema, the description is fully adequate. It covers purpose, effect, and prerequisites. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description of the 'uri' parameter in the schema is already clear. The tool description adds no extra meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action ('Permanently delete a table and all its rows'), identifies the resource ('table'), and distinguishes from siblings like akb_delete (which likely works on rows) by specifying 'table'. Also includes irreversibility and permission requirements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage only with admin role and when permanent deletion is intended, but does not explicitly mention alternatives or when not to use. Contrast with siblings like akb_alter_table or akb_delete is not provided, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes the tool as providing help and examples, but doesn't disclose whether it is read-only or any side effects. Given it's a help tool, the absence of explicit behavioral details is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with clear purpose. Each sentence adds value: what it does, how to start, and how to drill down. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a help tool with optional parameters and no output schema, the description is complete. It covers overview, drill-down, and starting point. All necessary context is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 usage context (e.g., 'Drill down') but does not add significant meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get help on AKB tools and workflows' using a specific verb and resource. Distinguishes from sibling tools, which are all operational tools, by being a meta-help tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: call with no arguments for overview, drill down into categories or specific tools, and 'START HERE' for new users. Lacks explicit exclusions or alternatives, but the purpose inherently serves as the alternative to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the mutation (flipping mode) and caching behavior, but omits authorization needs and potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-load the action and provide necessary detail without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one param and no output schema, the description adequately covers functionality, input identification, and return value, though it lacks error handling info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single param slug. The description adds value by clarifying that the vault is resolved automatically, going beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool freezes a publication's result to S3 and flips its mode to snapshot, distinguishing it from siblings like akb_publish 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use: to cache a publication's current result. It provides clear context but does not explicitly exclude alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It reveals that the response includes the canonical URI and that documents are automatically chunked and indexed for semantic search. This adds useful context about side effects (indexing) and response content, though it stops short of detailing error conditions or overwrite behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the essential action. Each sentence provides distinct value: the operation, the response URI and usage, and the automatic indexing side effect. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 14-parameter tool with no output schema, the description clarifies the most critical contextual points: the canonical URI for addressing the document and automatic indexing. It explains the response enough for an agent to use the URI, and the schema covers the rest. It could be improved by noting that it creates new documents only (not updates) and perhaps an example of the URI.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all 14 parameters with detailed descriptions (100% coverage), so the description doesn't need to restate them. It does add value by explaining the URI conventions (akb://vault/...), which relates to parameters like slug and parent, but this is more contextual than parameter-specific. The baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource: 'Store a new document.' It distinguishes from siblings like akb_put_file (file upload) and akb_update (updating existing docs) by explicitly stating it creates a new document. The additional detail about the canonical URI and automatic indexing reinforces the core purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it: for storing new documents that should be searchable and addressable via a canonical URI. It says 'Use that URI to address the document from every other tool,' which is practical guidance. However, it does not explicitly mention alternatives or when not to use it (e.g., use akb_update for modifying existing docs).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses S3 storage, MIME auto-detection, and URI format. Without annotations, it lacks details on file overwrite behavior, authentication needs, or size limits. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each serving a purpose: action+storage, URI usage, MIME handling. No fluff, efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key aspects (type of content, URI, MIME) and references siblings. Missing details on error states, permissions, or idempotency, but sufficient for a file upload tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema by explaining parent vs vault/collection derivation, MIME override conditions, and URI format. Schema coverage is 100% but description enriches context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool uploads a local file to a vault's S3-backed storage, specifies content types (PDFs, images, datasets) and distinguishes from akb_put for large binary content. It also explains the URI response and links to get/delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on when to use (binary content too large for akb_put) and mentions MIME override contexts. However, doesn't explicitly list alternatives for non-file uploads or including when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: slim response by default, depth semantics mimicking tree -L N, collection rows always emitted, filtering options, and return structure. This exceeds typical transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with front-loading of main purpose and clear subsections. Every sentence adds value, though it could be slightly more concise without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters with 100% schema coverage and no output schema, the description explains key behaviors (depth, addressing, response format). It lacks explicit pagination behavior details but covers most ground adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the precedence of uri over vault/collection, depth semantics, and defaults for include_summary and include_archived. Minor extra context beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it browses vault content (documents, tables, files) under a browse root, with two addressing methods. It distinguishes from siblings like akb_search and akb_get by focusing on hierarchical browsing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to address the browse root and suggests using URI when drilling down from previous responses. However, it does not explicitly differentiate from sibling akb_drill_down nor provide when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool creates a vault, and when external_git is used, it becomes a read-only mirror that rejects user writes and tracks on a polling schedule. However, it does not detail behaviors like potential failures or overwrite conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose. Every sentence contributes essential information, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should explain return values. It does not mention what the tool returns (e.g., vault ID or confirmation). Given the complexity of parameters, the description covers creation logic but is incomplete regarding outputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the relationship between external_git and read-only behavior, and that template is ignored when external_git is set. It also clarifies the public_access parameter's effect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'knowledge base vault', and distinguishes two modes: normal vault and read-only git mirror. It also mentions access control, effectively differentiating from sibling tools like akb_delete_vault and akb_list_vaults.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use the tool for vault creation and explicitly describes the git mirror alternative. However, it does not explicitly exclude other uses or mention when not to use the tool, though sibling context makes the purpose clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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 ('Get') but does not explicitly state it is non-destructive, idempotent, or discuss authentication or rate limits. It does explain the BFS traversal behavior via the 'hops' parameter, which adds partial transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no wasted words. It front-loads the core purpose ('Get a knowledge graph') and logically organizes the two usage modes and parameter details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the two input modes and explains key parameters like 'hops'. However, since there is no output schema, the description could briefly mention the structure of the returned graph (e.g., 'returns JSON with nodes and edges'), though the stated 'nodes and edges' provides a high-level idea.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, yet the description adds significant value by explaining the mutual exclusivity of 'uri' and 'vault', and disambiguating 'hops' from 'akb_browse.depth'. This context goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a knowledge graph with nodes and edges. It specifies two distinct modes: subgraph via 'uri' with BFS traversal, and full vault graph via 'vault'. This specificity differentiates it from sibling tools like akb_browse and akb_relations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use each parameter combination ('Provide `uri`' vs 'Provide `vault`'). However, it does not explicitly state when not to use this tool or mention alternatives like akb_relations for relation-specific queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description handles behavioral disclosure. It discloses idempotency (returns {created: false} if exists) and role requirement, which are key traits. It could mention whether it creates intermediate paths, but overall it is transparent enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences. The first sentence states the purpose, the second adds idempotency and role. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple creation tool with 3 parameters and no output schema, the description is fairly complete. It covers purpose, behavior (idempotent), role, and param hints. One minor gap: it doesn't specify the return format on success (e.g., {created: true}) but it's implied by the idempotency detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing baseline value. The description adds nuance to the 'path' parameter with examples ('api-specs' or 'docs/guides'), which clarifies usage beyond the schema. The 'summary' parameter is described as 'optional one-line description', adding context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create', the resource 'empty collection (folder)', and the scope 'inside a vault'. It distinguishes from siblings like akb_create_vault and akb_create_table by specifying 'collection'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions idempotency and the required role (Writer or higher), which are helpful usage constraints. However, it does not explicitly state when to use this tool vs alternatives or provide when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses the canonical URI returned, permissions inheritance, placement semantics, and supported column types. It does not detail side-effect behaviors like duplicate handling or error cases, but it provides meaningful behavioral context beyond a bare 'create' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences deliver the core action, canonical URI format, permissions model, column definition summary, and collection placement guidance. Every sentence earns its place, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter tool with no output schema, the description is largely complete: it explains the return value, placement, permissions, and essential column types. It does not address duplicates or error handling, but given the detailed input schema and the description's focus on the primary use case, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (88%), so the baseline is 3. The description adds value by explaining the collection parameter's grouping behavior, the vault-root alternative, and the response URI structure. It does not rehash every parameter, but the added semantics help disambiguate the most nuanced parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (create a structured data table) and the resource (a vault), with explicit placement rules via canonical URIs. It distinguishes this from sibling tools like akb_create_collection and akb_create_vault by focusing on table-specific behavior and collection grouping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool—creating a table either at the vault root or inside a collection—and explains how collection placement affects browsing in akb_browse. It does not explicitly name alternatives or exclusions, but the usage context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the operation cascades deletes for non-empty collections, emits a single git commit, and requires Writer role. It does not mention reversibility or error handling, but for a delete operation the transparency is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, each sentence provides essential information: purpose, conditional behavior, and a behavioral note. There is no redundancy or unnecessary detail, making it very concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete tool with no output schema, the description covers purpose, conditions for recursive use, role requirement, and git commit behavior. It lacks explicit mention of return values or prerequisites, but overall it is sufficiently complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by explaining the recursive parameter's behavior (required when non-empty) and the empty case. It also mentions the git commit behavior, which is not in the schema. This enhances understanding beyond the basic parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a collection, differentiating between empty and non-empty cases. It specifies the recursive parameter requirement and the effect of cascade deletion, making the purpose very specific and distinguishable from sibling tools like akb_delete or akb_delete_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use the recursive parameter (for non-empty collections) and mentions the role requirement (Writer or higher). It also describes the behavior for empty collections. However, it does not explicitly compare to alternative tools 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It reveals important traits: existing paths are skipped (idempotency), writer role is required, concept documents with type table/file are imported as regular documents, and the only supported format is currently 'okf'. It omits details like return values or partial failure semantics, but for an import tool this is substantial transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is six sentences, each carrying distinct information. It opens with the primary purpose, then details input shape, format, concept-doc behavior, idempotency, and permission requirement. There is no redundant or filler content; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and absence of an output schema, the description is remarkably complete. It covers input shape, format options, permission requirements, idempotent behavior, and special handling of concept documents. Minor gaps remain regarding partial success semantics, vault existence requirements, and return values, but these are not critical for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all four parameters (100% coverage), so the baseline is 3. The description adds value by explaining that `files` should use the exact shape returned by akb_export, clarifying `format` with 'currently okf', and elaborating on how concept documents are handled. This goes beyond the schema's restatements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Import a knowledge bundle into a vault.' It specifies the target resource (vault) and the action (import), and differentiates itself by referencing the exact shape returned by akb_export, which distinguishes it from sibling tools like akb_put that handle individual documents. The concept-document handling detail further clarifies its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: pass `files` as a {path: content} map, select `format`, and note that existing paths are skipped rather than overwritten. It implies when not to use it (when overwriting is needed) and gives a role requirement (writer). It does not explicitly name alternative tools, but the guidance is sufficient for differentiating from related operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 clearly states the share is public and no-auth, and describes the return value (canonical publication dict with `slug` and `share_url`). This provides sufficient transparency, though it could mention potential side effects like overwriting existing shares or limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences that front-load the main purpose and systematically cover the two main use cases. Every sentence adds value, and there is no wasted text. The structure aids quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (12 parameters, conditional logic, no output schema), the description adequately explains the different resource types and the return value. It could be more complete by mentioning default values or how to use the returned dict, but it covers the essential points for tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds meaning beyond the schema by explaining the conditional logic between resource types and the significance of the return value (`slug` is the only identifier needed). This helps an agent understand how parameters interact, going beyond mere repetition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a public, no-auth share URL for documents, files, or table queries. It specifies the verb 'Create' and the resource 'public share URL', distinguishing between resource types with conditional parameter usage. This effectively differentiates it from sibling tools like akb_set_public or akb_unpublish.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to pass `uri` (for document/file) versus `query_sql` + `vault` (for table_query), and mentions optional parameters like `password`, `max_views`, `expires_in`. It does not explicitly state when not to use this tool or provide alternatives, but the context is clear enough for an AI agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the destructive behavior (permanent deletion of all vault data) and authorization requirements. It leaves no ambiguity about the tool's impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences convey all essential information without redundancy. The description is front-loaded with the action and scope, and every sentence serves a clear purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, destructive action), the description covers all critical aspects: what is deleted, permanence, and authorization. No additional information is necessary, and it aligns with sibling context (e.g., akb_archive_vault).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the 'vault' parameter as 'Vault name to delete' (100% coverage). The tool description does not add new meaning to this parameter beyond restating the vault concept, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action (permanently delete a vault and all its data) and specifies the resource (vault). It lists the types of data deleted, distinguishing it from siblings like akb_archive_vault (which does not permanently delete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description warns that the action cannot be undone and requires owner or admin privileges, providing explicit usage context. It does not explicitly mention alternatives (e.g., archive), but the warning serves as a strong guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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 discloses that the tool fails if old_string is not found or appears multiple times (unless replace_all true), and mentions the OCC pin (base_commit) for concurrency control. It does not explicitly state that it permanently modifies the document, but the edit action implies mutation. Overall adequate without annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences long, all front-loaded. The first sentence gives the core action, the second clarifies scope, the third explains error conditions, and the fourth provides an alternative. Each sentence adds necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, no output schema, and no annotations, the description covers the tool's purpose, constraints, error handling, and usage boundaries. It could mention the return value (e.g., success indication), but the description is largely complete for an edit tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds meaning beyond the schema: it explains the uniqueness requirement for old_string, the interaction with replace_all, that new_string can be empty to delete, and the purpose of base_commit for optimistic concurrency control. This enriches the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool edits a single document by replacing exact text, specifying the scope ('one document') and contrasting with multi-document tool akb_grep. The verb and resource are precise, distinguishing it from siblings like akb_put, akb_update, and akb_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (single document exact-text replacement) and when not to ('For find-and-replace across many documents, use akb_grep with replace instead'). Also provides guidelines for unique old_string and replace_all behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses table auto-resolution, cross-vault naming, and read/write role requirements. Lacks mention of transaction behavior or result format, but core behavioral traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise two-sentence intro plus structured details. Every sentence adds necessary information with no redundancy. Front-loaded with core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully covers tool's purpose, parameter usage, and behavioral constraints (auto-resolution, role). No output schema, so return format not required. Complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% but description adds value: clarifies sql parameter meaning, explains vaults for cross-vault with prefix examples, and notes vault as shorthand. Goes beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Execute SQL on vault tables' with a specific verb and resource. Among 40+ sibling tools, only akb_sql handles SQL execution, making it uniquely identifiable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context for when to use this tool (executing SQL), including cross-vault syntax and role requirements. However, no direct exclusions or alternatives mentioned, though siblings list implies many non-SQL tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses key side effects: identity and git history are kept, old URI keeps resolving via redirect, graph links/publications are rewritten, and title is unchanged. This is substantial behavioral transparency, though it does not mention permission requirements or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, then side effects, then usage constraint and alternative. No redundancy; every sentence provides distinct value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutable operation with no annotations and no output schema, the description explains what changes, what remains, and side effects like redirects and link rewrites. It does not mention what happens if both collection and slug are unchanged (likely an error), but the constraint implies it. Overall fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaningful constraint: at least one of collection or slug must change, which is not evident from the schema alone. It also clarifies that title is not a parameter, reinforcing the distinction from akb_update.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool moves or renames a document, changing its collection and/or slug while preserving identity and git history. This clearly distinguishes it from siblings like akb_update (title change) and akb_edit (content edit).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: to move/rename a document. Also gives an alternative: use akb_update to change the displayed title. The constraint that at least one of collection or slug must change provides clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, but description discloses the return format ({deleted: N}) and the nature of the operation (removal). Could mention idempotency or error handling for missing slugs/uris, but is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with purpose, no fluff. Every sentence adds useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero annotations and no output schema, the description covers both parameters, return value, and an important edge case. It is self-contained and sufficient for confident use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant value beyond schema descriptions: explains the semantic difference between slug and uri, and clarifies that table_query publications lack URI so must use slug.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Remove publication(s)' and distinguishes between removing one by slug or all by URI, with a specific edge case for table_query publications. It contrasts with siblings like akb_publish 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use slug vs uri, and mentions the handy use case for re-publishing. Provides enough context to choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description thoroughly discloses behavior: default literal matching (ILIKE) vs regex, case sensitivity, replace side effects (git commit + re-index per doc), and response shapes with truncated flag. It clearly communicates that replace is a mutation and advises alternatives for single-document edits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is comprehensive but slightly verbose. It is well-structured with front-loaded purpose and sibling distinction, and logically organized sections. Every sentence adds value, but could be tightened slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete: covers search behavior, sibling comparison, response shapes, parameter guidance, and replace side effects. No output schema is provided, so the description adequately explains return values and shapes. For a complex tool with 9 parameters, this is very complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant value beyond parameter descriptions: explains that pattern is literal by default (ILIKE) and when to use regex, replaces semantics including backreferences, and response shapes for count_only and files_with_matches. Provides usage guidance for each option.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search for exact text or regex patterns across document content.' It distinguishes from akb_search by contrasting exact string matches vs semantic/meaning-based search, and provides specific use cases (specific terms, URLs, code snippets, version numbers).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool (exact matches) versus akb_search (semantic). Also advises when to use akb_edit for single-document edits. Provides detailed guidance on the three response shapes and when to use each (e.g., if truncated, use count_only/files_with_matches instead of increasing limit).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. It discloses hybrid retrieval internals, the meaning of total_matches (not corpus-wide, top-K only), truncated=true behavior, degraded=true behavior, and degradation_reason. This goes far beyond basic safety and is exceptionally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every sentence serves a purpose: core method, alternative, follow-up navigation, response semantics, truncated handling, degraded handling. Logical flow from purpose to exceptions; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 8 parameters, description explains response fields (`returned`, `total_matches`), edge cases (`truncated`, `degraded`), and follow-up actions. It fully equips an agent to use results safely and to understand failure modes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 88% of parameters with descriptions. The description adds nuance to `query` (handles natural-language questions and short keyword queries) and clarifies that exact matches should go to grep, but it doesn't elaborate on filter parameters beyond schema. This is a moderate addition over the high baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'Search documents with hybrid retrieval — dense vector (semantic) fused with BM25 sparse (keyword) via Reciprocal Rank Fusion.' This clearly states the verb (search), resource (documents), and method. It distinguishes from akb_grep ('exact string / regex matches') and akb_browse via sibling context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly directs users to akb_grep for exact string/regex matches, and toward akb_drill_down/akb_get for full content. Also instructs fallback to akb_grep when truncated or degraded, providing clear when-to-use vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![akb MCP server](https://glama.ai/mcp/servers/dnotitia/akb/badges/card.svg)](https://glama.ai/mcp/servers/dnotitia/akb)

Score Badge

Copy to your README.md:

[![akb MCP server](https://glama.ai/mcp/servers/dnotitia/akb/badges/score.svg)](https://glama.ai/mcp/servers/dnotitia/akb)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dnotitia/akb'

If you have feedback or need assistance with the MCP directory API, please join our Discord server